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 ContentCreator. For information about restrictions see Chapter Restrictions in the ContentCreator.

For information about transfer types which are supported for drag-and-drop please see also page Drag-and-drop.

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 component 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 template set 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 and Long
• mode="time": FirstSpirit-Editor and Long

The data type "Date" can not be used for the modes date and time! (For information about the data types please see page Creating columns).

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 SiteArchitect and the time zone of the FirstSpirit Server is taken into account.
  Example: SiteArchitect 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 SiteArchitect, 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 SiteArchitect 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 SiteArchitect 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/yyyy HH:mm

But you can use the parameter format 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 an error message will be displayed in SiteArchitect and the input will not be saved (manual entries are not possible in ContentCreator). 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.

Note on the effect of preset="modified" in ContentCreator: While the date of the last change is set into the form in SiteArchitect when the modification is made itself, it is set in ContentCreator only when saving the modification.

Moreover, the values default and copy can be set:

If preset="default" is set, the fall-back 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

searchRelevancy

This parameter can be used for determining the weighting of content of this input component in search results (SiteArchitect: Global search (→Documentation FirstSpirit SiteArchitect), search in data sources | ContentCreator: search in report area). For example, using this parameter, template developers may specify that elements that contain a search term in a headline input component should be displayed more prominently in search results than elements that only contain the search term in a body text input component. Additionally, contents of individual input components may be configured so that they be ignored during indexing for search, which may increase indexing performance.
Input components may be configured with the following values to specify their contents' weight in search indexing:

• none: The contents of an input component that is configured with this search relevancy value will not be indexed. Pages, sections, and datasets which contain contents in input components configured with this search relevancy value will not appear in search results if the search term only appears in these input components. Searching for contents of such input components using drag-and-drop will yield no results ("The field is not eligible for search, as it is marked non-relevant for searching."). Such fields are also marked accordingly in "Simple Search" in data sources ("Not eligible for searching.").
• default: The input component's content receives default weight in the search index (default setting).
• high: The contents of an input component that is configured with this search relevancy value will be displayed more prominently in search results (exception: search for datasets). This means that if a search term appears in both an element with an input component configured with high search relevancy and an element with an input component configured with default search relevancy, the element which contains the search term in a high-relevancy input component will be shown in a higher position in search results.

If the parameter is not specified for an input component, the component's contents will be indexed with a default weight (searchRelevancy="default").

Note: Header fields of snippets (tab Snippet in templates, "Label" field) are also indexed. If an input component is configured with a weighting none (searchRelevancy="none") but its value is included in the template's snippet header field, searching for the input component's value will cause the associated element to appear in search results

Changing the weighting setting of an input component in a template does not immediately affect existing elements based upon that template, and search results will continue to reflect the old weighting until elements based upon that template are modified (at which time they will be reindexed in the background). Alternatively, the entire project or parts of it may be reindexed via a schedule task or the FirstSpirit APIs, which does not require elements to be changed (see FirstSpirit Manual for Administrators, Chapter "Rebuild search index (→Documentation for Administrators)"). However, reindexing large numbers of elements is memory and CPU-intensive and should only be performed during a planned maintenance period!

For further information, see

• interface GomSearchRelevancy (package de.espirit.firstspirit.access.store.templatestore.gom, FirstSpirit Access API)
• interface SearchService (package de.espirit.firstspirit.access.search, FirstSpirit Access API)
• interface QueryAgent (package de.espirit.firstspirit.agency, FirstSpirit Access API)

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 over two rows with a frame.

If YES (...singleLine="YES"...) is specified the input component is displayed in one row without a frame.

To ensure uniform layout of the input components it is advisable to enter the following for the other input components which support this attribute (e.g. COMBOBOX, 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.

useLanguages="YES" will potentially no longer be evaluated in FirstSpirit version 5.2R5 and higher. See also parameter forbidPolyglotDataHierarchy (FS_CATALOG).

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 Language templates (→Documentation for Administrators)) 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 specify a description of how the input component is to be used and filled by the editor. The text defined here is displayed as a tooltip on mouse-over at the relevant input component.

The text should serve as a guide for the editor and be as short as possible, understandable and relevant. It should match the label (label parameter) and complement it appropriately.
Make sure to use terminology that the editor knows and expects.

Example:

...description="Please enter the text for the headline here (H1)."...

Tip: If you would like to know how to better support and guide editors when filling input components, take a look at the chapter on Rules and other parameters and functions of forms.

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 SiteArchitect and it can not be saved (manual entries are not possible in ContentCreator). 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. Exception: the specification of the year is displayed with four digits. I.e. the default format is dd/MM/yyyy HH:mm in the project language English, dd.MM.yyyy HH:mm in the project language German.

Example project language English:

24/01/2010 10:52 

Example project language German:

24.01.2010 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

Use the label parameter to define the label of the input component.

Choose a label that is as short and meaningful as possible.
In combination with a relevant description (description parameter), you can help the editor to use the input component correctly and successfully.

Example:

... label="Headline (H1)" ...

Overview

length

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

The parameter expects an integer value.

Overview

PositiveInteger	Positive integer
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"
Relevancy	Definition of relevancy for search NONE Irrelevant DEFAULT Normal relevance HIGH High relevance
DatePreset	How to deal with default values Modified The date of the last change is used as default value (and can not be edited) Created The date of creation of the object is used as default value Copy The value entered by the editor is copied directly into the input component, subsequent changes do not have any effect Default The fall-back value defined in the form is used, as long as a value will be set manually
String	A random character string
YesNo	Switch to apply an attribute or not NO Do not apply attribute YES Apply attribute
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
DateTimeMode	Input mode DATETIME Selection of date and time DATE Selection of a date TIME Selection of a time
LanguageAbbreviation	Language abbreviation, e.g. DE, EN, FR or * for return values

Example

An example of the input component DATE:

<CMS_INPUT_DATE name="IDENTIFIER" useLanguages="YES">
  <LANGINFOS>
    <LANGINFO lang="*" label="TEXT_FALLBACK" description="TEXT_FALLBACK"/>
    <LANGINFO lang="DE" label="TEXT_DE" description="TEXT_DE" format="FORMAT"/>
    <LANGINFO lang="EN" label="TEXT_EN" description="TEXT_EN" 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>