CMS_INPUT_DATE

CMS_INPUT_DATE

The editor can use the CMS_INPUT_DATE input component to either manually enter a date and/or time directly or to select it with the help of the calendar/time input component. The format attribute can be used to define a specific format for the input and display of date and/or time in the input component.

Languages and time zones
CMS_INPUT_DATE generates a "language-specific" display of date and time specifications. This means that date and time are displayed depending on the language of the client, selected on the FirstSpirit start page ("locale") in a format which is typical for the respective country.

By default (mode="datetime"), date and time are first saved irrespectively of the time zone in which the editor is: they are saved always in in UTC (Universal Time Coordinated).
The Central European Time (CET), which is used in Germany, differs by one hour for example from UTC, this time zone is identified by UTC+1: therefore, in the time zone CET it is one hour later than in the time zone UTC. All further explanations on this page refer to UTC.
In case of the preview, generation and display of date and time in the input component the time zone, in which the actual FirstSpirit user is, as well as summer / winter time (DST, Daylight Saving Time) are taken into account: the time zone of the client is crucial for what time/date is displayed in the input component, the time zone of the FirstSpirit server is crucial for what time/date is used in the preview and for the generation.

Examples
1) Display of date and time in the input component: If the information "10.09.09 08:00" is entered and saved in the time zone UTC+1 (e.g. Germany), it will be displayed as "10/09/09 07:00" in the time zone UTC (e.g. Great Britain) if "English" is selected as language of the client.
2) Display of date and time in the preview/generation: The server is in the time zone UTC+12, the client is in the time zone UTC+3. If an editor enters the point in time "01.01.2010 01:00:00" in the client, "01.01.2010 10:00:00" will be displayed in the preview/generation; the server is 9 hours ahead to the client.

Saving and output of information about time and date differs partially concerning the modes date and time, as well as the behaviour when using CMS_INPUT_DATE in table templates. Please see parameter mode.

Information about time zones and DST derive from the used JDK. In order to work with the latest data for each time zone these information can be updated using the "Timezone Updater Tool" (short "TZUpdater") from Sun without having to import a new JDK. For further information please see: General information about time zones in Java ReadMe page for the Timezone Updater Tool Download page for the Timezone Updater Tool

When outputting the values of the input component CMS_INPUT_DATE in templates the data type Date will be changed into the data type GregorianCalendar. For this reason, the methods of the data type GregorianCalendar must be used in templates.

This input component is also supported in FirstSpirit WebClient. For information about restrictions see Chapter Restrictions in the WebClient.

Access-API example use case
The exemplary implementation DateEditorValueExample shows some simple examples of use for the reading, writing and creating access to the data object (DateEditorValue) and its date object (java.util.Date) of the input component by means of the FirstSpirit Access-API.

• Example of use: DateEditorValueExample
• Data object: DateEditorValue
• Data type: java.util.Date

Parameter

The following table gives the parameters of the DATE input component.

Overview

name

The attribute "name" is the variable name of an input component with which the the result object of the input component can be used in the templates - with the help of $CMS_VALUE()$ - or the content can be output.

Overview

allowEmpty

The "allowEmpty" parameter is used to specify whether a value has to be entered for an input value or not.

If allowEmpty="YES" input is not mandatory; however, it is if allowEmpty="NO".

Input components with allowEmpty="NO" are also called mandatory input components.

The default value for allowEmpty is YES.

Overview

allowInput

As a default it is not possible to manually enter a date in a DATE input component, as the selection is usually made via the calendar.

However, if the template developer would like to offer the user the possibility of entering the date manually too, this is done using the parameter allowInput.

Manual inputs are also allowed by specifying YES for the parameter ( allowInput="YES").

Overview

convertEntities

The "convertEntities" attribute is used to convert special characters entered in the input components for output in HTML characters.

There are three forms:

• convertEntities="NONE" (standard)
• convertEntities="STANDARD"
• convertEntities="QUOTE"

With the NONE form, no conversion rules whatsoever are applied.

If STANDARD is given the conversion rules in the "convert" area of the selected conversion rule of the presentation channel are applied.

The form QUOTE explicitly includes STANDARD too. However, the "quote" area of the conversion rule is also applied.

Overview

hFill

An input component is always displayed with a pre-defined width.

However, if the input component is to use the full available display width the parameter hFill must be given with the value YES .

Overview

hidden

With the "hidden" parameter an input component can be hidden from the editor.

If hidden="YES" the input component is not visible for the editor, if hidden="NO" it is visible.

The default value for hidden is NO.

Overview

mode

Using the parameter mode you can define if

• date and time
• only a date or
• only a time

are to be selected by the editor and saved in the input component.

The following values can be set: date, time and datetime.
If mode="date" is set the editor can only select a date, if mode="time" is set the editor can only select a time. In these cases the editor will get only the calendar or only the time input component. If mode="datetime" is set date and time can be selected and saved at the same time; this is also the default setting if mode is not set at all.

In the date mode the time "00:00" (UTC) will be saved by default in addition to the date which the editor selects, in the time mode the date "01.01.1970" will be saved by default in addition to the time which the editor selects. This information will not be visualised in the input component. Please bare in mind that if the mode will be changed from datetime to date or time for values which are saved already in the input component, the saved time or date will be reset to "00:00" o'clock or "01.01.1970". On the contrary, if date or time are changed to datetime, for the information which has not been selected by the editor "00:00" o'clock or "01.01.1970" will be saved. Also when using the saving modes for default values (parameter preset, see below) "00:00" will be saved as time in the case of mode="date", in the case of mode="time" "01.01.1970" will be saved as date.

date and time in different time zones
While for mode="datetime" the current time zone and summer / winter time are taken into account for preview, generation and display of date and time in the input component (please see section "Languages and time zones" in the introduction above), the same date and time are displayed (in the input component, preview and generation) in the case of mode="date" and mode="time" in all time zones.
If, for example, the date "01.01.1970" and/or the time "00:00" is entered in the time zone UTC+1, "01.01.1970" and/or "00:00" will be displayed in all time zones.

Using CMS_INPUT_DATE in table templates / data sources
CMS_INPUT_DATE can be made available to the editor not only in the Page Store (pages and sections), but also in data sources. The usage in both stores can differ.

According to the mode, the following data types can be used in table templates:

• mode="datetime": FIRSTspirit-Editor, Long and Date
• mode="date": FIRSTspirit-Editor und Long
• mode="time": FIRSTspirit-Editor und Long

The data type "Date" can not be used for the modes date and time!

The selection of the datatype controls how date and time are displayed in the input component, preview and generation:

• If the data type FIRSTspirit-Editor is used, date and time are displayed like in the Page Store.
• If the data type Date is used (only available in the mode datetime), date and time are saved depending on the time zone in which the FirstSpirit Server currently is. The difference between the time zone of the client and the time zone of the server is taken into account.
  Example: The client is in the time zone UTC+1, the FirstSpirit Server is in the time zone UTC. If the editor enters "01.02.2010 00:30:00" in the client, it will be saved as "31.01.2010 23:30:00" in the database. "01.02.2010 00:30:00" is still displayed in the input component, but "31.01.2010 23:30:00" is displayed in the preview and on the generated page.
  In contrast, date and time are saved in the Page Store in UTC if the mode datetime is set.
• If the data type Long is used, date and time are saved and displayed in the client in UTC like in the Page Store. They are displayed independent of the time zone in preview and generation, i.e. as they are entered by the editor.
  Example: If the editor enters the time "15:00:00", "15:00:00" will be displayed in the client and in the generation in all time zones.

Formatting of time and date specification
Selected dates and/or points in time are displayed in the input component like this in the project language English by default:

dd/mm/yy HH:mm

But you can use the parameter format (see below) to override this format, i.e. if a format is specified by the parameter format this will also be used for the visualisation of the selected date and/or time in the input component. For this reason, the format defined by format should fit to the mode which is defined by mode. Otherwise, the selected time and/or date will not be visualised in the input component. I.e., if mode="time" is set, format should contain specifications about how to format of a time (e.g. specification of hours and minutes), if mode="date" is set, format should contain specifications about how to format a date (e.g. specification of day, month and year), if mode="datetime" is set, format should contain specifications about how to format a date and a time.

If allowInput="yes" (see above) is set, the editor must enter date and time in the requested format. Otherwise in the JavaClient an error message will be displayed and the input will not be saved. If mode="date" is set, but format requires the specification of a time, the editor can enter a point in time, but this will be set to "00:00" when it is saved, analogously in the case of mode="time" and default values.

The format of date and time specification in the output (e.g. HTML) is defined independently from the parameter mode for example by using methode format. Please pay attention, too, that the format of the output fits to the mode which is defined by mode and to the format which is defined by format.

Overview

noBreak

The noBreak parameter can be used to suppress automatic line break after an input component.

The noBreak parameter must be given with value "YES" (noBreak="YES") to suppress the automatic line break.

Overview

preset

Using the attribute preset you can define, if a default value (see also chapter Default values) is to be stored or not. If preset="created" is set, the date of creation of the object is used as default value, it can be edited using the input component; if preset="modified" is set, the date of the last change is used as default value, this can not be edited via the input component.

Moreover, the values default and copy can be set:

If preset="default" is set, the retrieval value defined in the form is used. If this value in the form is changed later on, these changes will be affect all usages of this default value in the input components maintained by the editor, as long as a value will be manually set in the input component. This is the default setting. If preset="copy" is set, the value entered by the editor is copied directly into the input component. Subsequent changes to the default value in the form do not have any effect on the usages of this default value in the input components maintained by the editor.

If mode="time" (see above) is set too, "01.01.1970" will be saved as date, if mode="date" is set, "00:00" will be saved as time.

Overview

singleLine

The singleLine parameter can be used to specify whether an input component is to be displayed in one row (without frame) or not.

If the parameter is not given the input component is displayed in one row - without a frame.

If NO (...singleLine="NO"...) is specified the input component is displayed over two rows with a frame.

To ensure uniform layout of the input components it is advisable to enter the following for the input components which support this attribute (e.g. COMBOBOX, DATE, NUMBER, TEXT and TOGGLE) singleLine="NO".

Overview

useLanguages

The useLanguages parameter can be used to specify whether or not an input component is to store different or deviating values for different languages (multi-lingual maintenance).

If the parameter is not given, deviating values are stored for the different languages as a default.

If NO (...useLanguages="NO") is specified, one value is stored for all languages.

Overview

LANGINFOS

Using the tag LANGINFOS language-dependent information can be defined for each input component, e.g. which title is to be used for the input component in the different project languages (parameter label), which tooltip is to be displayed (parameter description) etc. For reasons of clarity, definitions which are identical in multiple languages will be merged. For example,

<LANGINFOS> 
 <LANGINFO lang="*" label="Datum"/> 
 <LANGINFO lang="DE" label="Datum"/> 
 <LANGINFO lang="EN" label="Datum"/>
</LANGINFOS>

will be merged to

 <LANGINFOS> 
 <LANGINFO lang="*" label="Datum"/> 
</LANGINFOS>

after saving.

Up to and including FirstSpirit version 4.2R2 language definitions will be deleted only in the case if the values are identical in all languages (as in example above). Furthermore, only the parameters lang, description and label are taken into account when merging.

Since FirstSpirit version 4.2R4 all parameters are taken into account (e.g. format and length). Furthermore, language definitions are also merged within LANGINFOS tags, if they are identical in at least two languages. For example,

<LANGINFOS> 
 <LANGINFO lang="*" label="Date" format="dd.MM.yy"/>
 <LANGINFO lang="DE" label="Date" format="dd.MM.yy"/>
 <LANGINFO lang="EN" label="Date" format="MM/dd/yy"/>
</LANGINFOS>

will become

 <LANGINFOS> 
 <LANGINFO lang="*" label="Date" format="dd.MM.yy"/>
 <LANGINFO lang="EN" label="Date" format="MM/dd/yy"/>
</LANGINFOS>

after saving.

The definition for the fallback value (*) will not be deleted in any case. If there are two or more language definitions with identical values the first one will be maintained, the other will be deleted.

IMPORTANT: Up to and including FirstSpirit version 4.2R2 at least one definition for the fallback labelling ("*") must be given:

<LANGINFOS>
 <LANGINFO lang="*" label="TEXT"/>
</LANGINFOS>

From FirstSpirit version 4.2R4 the fallback definition can be omitted. In this case, the language which is defined first will be used automatically as fallback value. For example,

<LANGINFOS>
 <LANGINFO lang="EN" label="Date"/>
 <LANGINFO lang="DE" label="Datum"/> 
</LANGINFOS>

will become

 <LANGINFOS> 
 <LANGINFO lang="*" label="Date"/>
 <LANGINFO lang="DE" label="Datum"/> 
</LANGINFOS>

after saving.

LANGINFO

The LANGINFO tag is used to give values or attributes for a language as well for use as fallback values.

In order to state values or attributes for a language it is necessary to give the abbreviation of the project language in the lang parameter:

...
<LANGINFO lang="DE".../>
...

Fallback values are given with the special language abbreviation * ("for all languages"):

...
<LANGINFO lang="*".../>
...

The lang parameter is a mandatory parameter.

Overview

lang

The lang parameter is used to give the language abbreviation which is entered in the server properties see FirstSpirit Manual for Administrators, Chapter "Language templates") to specify for which project languages the definitions are to apply, e.g. DE for German, EN for English, FR for French etc. The following characters can be used as often as required: -, _, 0-9 and A-Z. Lower case letters are transformed automatically into upper case letters after having saved the template. In addition * can be used for fallback values.

Overview

description

The description parameter can be used to give a description which is used to display a tool tip (mouse-over).

Overview

format

Using the parameter format you can define how time and date specifications are to displayed in the input component.

If a manual input of time and/or date is admitted (allowInput="YES") it must be entered in the form which is defined by format. If it does not correspond with the defined format, the entry will be displayed in red letters to the editor in the JavaClient and it can not be saved. To prevent such incorrect entries it would make sense to indicate the requested format in the labelling (parameter label) or in the tooltip used for the description of the input component (parameter description).

The calendar/time input component does not depend on the defined format. This input component can be configured by using the parameter mode (see above).

The following formatting symbols can be used amongst others:

• yyyy: specification of the year, four-digit (e.g. 2010)
• yy: specification of the year, two-digit (e.g. 96)
• MM: specification of the month, in case of one-digit beginning with 0 (e.g. 03)
• MMM: specification of the month, three lettered language-specific abbreviation (e.g. Mar)
• MMMM: specification of the month, long, language-specific (e.g. March)
• d: day of the month (e.g. 26)
• D: day of the year (e.g. 145)
• F: day of week in month (e.g. 4)
• h: hour, 12-hour notation (e.g. 9)
• H: hour, 24-hour notation (e.g. 21)
• m: specification of the minute (e.g. 13)
• s: specification of the second (e.g. 22)
• E: name of the weekday, three lettered language-specific abbreviation (e.g. Wed)
• EEEE: name of the weekday, long, language-specific (e.g. Wednesday)
• w: calender week (e.g. 12)
• W: week in month (e.g. 4)
• a: specification of AM / PM
• Z: time zone according to RFC 822 (e.g. +0200)

(See also data type GregorianCalendar and Class SimpleDateFormat.)

These symbols can be used separately or combined. Space characters, dots, colons, comma, hyphens, slashes etc. can be used as separator. Additional text can be inserted by using simple inverted comma, e.g. 'Date:' dd.MM.yyyy, 'time:' HH:mm.

If the parameter format is not set date and time will be displayed language-dependent and two-digit by default. I.e. the default format is dd/MM/yy HH:mm in the project language English, dd.MM.yy HH:mm in the project language German.

Example project language English:

24/01/10 10:52 

Example project language German:

24.01.10 10:52

The format which is defined by format can differ from that used for output. I.e. date and time can be displayed in the input component in the format dd.MM.yyyy, HH:mm (example: 24.01.2010, 10:52) but only the date can be output (example: 24.01.2010) or a "language-specific" English representation (example: 24/01/10 10:52).

Overview

label

The label parameter is used to give the surface labelling for input and visualisation components.

Overview

length

The length parameter can be used to specify the width of the input component.

The parameter expects an integer value.

Overview

LanguageAbbreviation	Language abbreviation, e.g. DE, EN, FR or * for return values
PositiveInteger	Positive integer
YesNo	Switch to apply an attribute or not NO Do not apply attribute YES Apply attribute
String	A random character string
DateTimeMode	Switch for setting the date mode of a form. DATETIME Use both, date and time. DATE Use date only. TIME Use time only.
DatePreset	Define the preset mode for dates. Modified Set each time when modified. Created Preset once with creation date. Default Retrieve default from definition, if no value is set. Copy Copy default from definition and save automatically.
ConvertEntity	Switch with which to define the conversion rule NONE Do not use any conversion rules STANDARD Use the conversion rules of the "convert" area QUOTE Use the conversion rules of the "convert" and "quote" area
Designator	Unique identifier of variable length; must start with a letter or underscore and may only contain the characters "A-Z", "a-z", "0-9" and "_", e.g. "fr_st_varName"

Example

An example of the input component CMS_INPUT_DATE:

<CMS_INPUT_DATE name="IDENTIFIER" useLanguages="YES">
  <LANGINFOS>
    <LANGINFO lang="*" label="TEXT" description="TEXT"/>
    <LANGINFO lang="DE" label="TEXT" description="TEXT"  format="FORMAT"/>
    <LANGINFO lang="EN" label="TEXT" description="TEXT"  format="FORMAT"/>
  </LANGINFOS>
</CMS_INPUT_DATE>

Example of use in the template syntax

An example which outputs a date st_date in different formats:

$CMS_VALUE(st_date)$<br>
$CMS_VALUE(st_date.format("yyyy"))$<br>
$CMS_VALUE(st_date.format("hh.mm"))$<br>