Calendar form field type
The calendar form field type provides a text box for entry of a date. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value. If the field has a saved value this is shown in the text box. Otherwise the default value, if any, is displayed.
- type (mandatory) must be calendar.
- name (mandatory) is the unique name of the field.
- label (mandatory) (translatable) is the descriptive title of the field.
- default (optional) is the default date. This must be given in the same format as specified by the format argument. You can put "NOW" to have current date or time information in the given format.
- description (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the text box.
- readonly (optional) is whether the text box is read-only (true or false). If the text box is read-only, the date cannot be changed, but can be selected and copied. No calendar icon will be shown.
- disabled (optional) is whether the text box is disabled (true or false). If the text box is disabled, the date cannot be changed, selected or copied.
- class (optional) is a CSS class name for the HTML form field. It is recommended to use the "Bootstrap2 Relatives sizing" (see code examples below).
- format (optional) is the date format to be used. This is in the format used by PHP to specify date string formats (see below). If no format argument is given, '%Y-%m-%d' is assumed (giving dates like '2017-05-15').
- filter (optional) is time zone to be used. There are two values; server_utc and user_utc. The first one is server time zone and the later is user time zone as configured in global configuration and user information respectively.
- translateformat (optional): If set to true, the calendar will use a language string to determine the format. The `format` attribute is ignored. If false, the `format` attribute is used (same behaviour as today). (starting with 3.7.0)
- showtime (optional): If set to true and
translateformatis true, the language key
DATE_FORMAT_CALENDAR_DATETIMEis used, otherwise
DATE_FORMAT_CALENDAR_DATE. (starting with 3.7.0)
- timeformat (optional): can be set to 12 (and specify AM or PM) or 24 (starting with 3.7.0)
- singleheader (optional): if set to false, the year and the month selection will be set on two separates lines, with independant selection (starting with 3.7.0)
- todaybutton (optional): if set to true, a button is added at the bottom of the datePicker to select the date of the current day (starting with 3.7.0)
- weeknumbers (optional): if set to true, a column is added at the left of the datePicker to display the number of the week in the current year (starting with 3.7.0)
- filltable (optional): if set to true, dates of the previous and next month is added at the top and the bottom of the current month to fill the grid (starting with 3.7.0)
- minyear (optional): set a signed integer for a number of years (-10, -2, 0, 7, 12, ...) to define the relative lower limit for the year selection. The user could not select a year before your limit (starting with 3.7.0)
- maxyear (optional): set a signed integer for a number of years (-10, -2, 0, 7, 12, ...) to define the relative upper limit for the year selection. The user could not select a year after your limit (starting with 3.7.0)
Example for a light DatePicker XML field definition:
<field name="mycalendar" type="calendar" default="2017-05-15" label="Select a date" description="" class="input-small" required="true" filter="user_utc" showtime="false" todaybutton="false" filltable="false" translateformat="true" />
Example for an advanced DatePicker XML field definition:
<field name="mycalendar" type="calendar" default="2017-05-15" label="Select a date" description="" class="input-medium" required="true" filter="user_utc" format="%Y-%m-%d" singleheader="true" showtime="true" timeformat="12" todaybutton="true" weeknumbers="true" filltable="true" minyear="-3" maxyear="5" />
|d||Day of the month, 2 digits with leading zeros||01 to 31|
|a||A textual representation of a day, three letters||Mon through Sun|
|e||Day of the month without leading zeros||1 to 31|
|A||A full textual representation of the day of the week||Monday through Sunday|
|w||Numeric representation of the day of the week||0 (for Sunday) through 6 (for Saturday)|
|j||The day of the year (starting from 0)||001 through 366|
|B||A full textual representation of a month||January through December|
|m||Numeric representation of a month, with leading zeros||01 through 12|
|b||A short textual representation of a month, three letters||Jan through Dec|
|Y||A full numeric representation of a year, 4 digits||1999 or 2003|
|y||A two-digit representation of a year||99 or 03|
|p||Lowercase Ante Meridiem or Post Meridiem||am or pm|
|P||Uppercase Ante Meridiem or Post Meridiem||AM or PM|
Note: The format in which dates are stored in the params.ini file is that specified by the format argument. Since there can be language-dependent elements to this format (for example, the '%A' specifier), you need to be careful not to use such elements if there is a possibility that the front-end and back-end languages may be different.
Note: The calendar form field type does not support non-Gregorian calendars. If you need to support non-Gregorian calendars then you will need to create a custom form field type to support your calendar.
Standard associated filters
- user_utc - Calculates the specified value to the time of Greenwich, according to the user time zone settings.