frevvo Latest - This documentation is for frevvo v10.3. v10.3 is a Cloud Only release. Not for you? Earlier documentation is available too.
Working with Dates and Times
Capturing dates and time accurately is important because frevvo forms and workflows are designed to be used anywhere in the world, streamlining our customer's business processes. This chapter will consolidate information from several other documentation chapters related to working with dates and times in frevvo.
Date, Time, and Date/Time Controls
The date control allows the user to enter a date, time, or date/time combo. The designer can choose from a variety of formats for each type.
Designers can add a date picker via the Style Properties tab.
The Date control denotes a day and has no dependencies on time zone.
The Time control denotes the time of the day and has no dependencies on time zones or offsets. It will not shift based on whether or not Daylight Savings Time is observed in a time zone.
The Date/Time control relies on the time zone of the browser. The time portion will be calculated based on the date and whether or not Daylight Savings Time is observed in that time zone. The Date/Time control type is meant to represent a point in time, so certain functions in the Visual Rule Builder (year, month, day, hour, minute) are not available on this control type.
If the form cannot infer the browser time zone, the Date/Time control will display in UTC.
For example, the time 5:00 PM is entered into a Time control and the date 2/4/2020 plus 5:00 PM into a Date/Time control by a user located in the America/New_York (Eastern Standard Time). When the submission is viewed in the EST time zone, the Time Control displays 5:00 PM. This value will not change. The time portion of the Date/Time control also displays 5:00 PM, because it takes on the timezone of the browser (EST) and it is not further adjusted because Daylight Savings Time is not observed in EST on February 4th.
If the submission is viewed in Tijuana (Pacific Standard Time), the Time Control will display 5:00 PM as it did in EST, since it has no dependency on time zone. However, the Time portion of the Date/Time control will show 2:00 PM because it will be adjusted by the browser time zone to PST.
Business Rules can be applied to the Date/Time control in all variations. See the Rules Examples chapter containing numerous examples.
Please review the Time Zone documentation to understand how Time Zones work when initializing date, time, and date/time controls using business rules and _data.
Date, Time and Date/Time Submission Values
frevvo saves Date and Time control values in the submission xml document exactly as entered, but converted to ISO format. These values will display as entered, regardless of viewer's time zone, when the submission or workflow step is viewed.
frevvo saves Date/Time control values in the submission document in Coordinated Universal Time (UTC), also in ISO format. The indicator "Z" is appended to the end of the string to denote UTC time. This value will display in the user's browser time zone when the submission or workflow step is viewed.
Here is a form with Date, Time, and Date/Time controls entered by the user at run-time in the New York time zone.
In the submissions document, notice that the date and time are saved as entered. You can see the time is '10:43:00' which is 10:43 AM in ISO format. However, the Date/Time control value is saved in UTC '14:43:00Z' which is 10:43 AM EST converted to UTC.
ISO Formats
Date: YYYY-MM-DD
Time: HH:MM:SS
DateTime: yyyy-mm-ddThh:mm:ssZ
Date, Time and Date/Time controls display with UTC offsets in the Submission CSV Export.
Date, Time, Date/Time Formats
Designers can select formats for Date, Time, and Date/Time controls from a variety of options. The Date Format only controls what the user sees in the form and not what is stored in the submission xml.
Date Format
The Date Format property applies to Date controls and the Date portion of the Date/Time control. The default, recommended format is "Automatic", which is a locale-specific date format. The designer has the option to set a particular date format independent of the locale by using the format field, but this is not recommended. Read this documentation for more information about date controls and internationalization.
Available Date Formats consist of three different separators (dash '-', slash '/', or period '.') and four date display formats (DD/MM/YYYY, MM/DD/YYYY, YYYY/MM/DD, or Mmm/DD/YYYY). European date formatting is supported.
When the Date Format property is set to a specific format, dates entered into the form will be translated and reformatted to match the selected format.
- A date typed into a form field will be reformatted to match the selected Date Format
- A date entered into a form field will be translated according to the selected format. For example, if you choose a European format of DD-MM-YYYY and the user enters 10-05-2009, the date value will be translated as May 10, 2009. If you choose a US format of MM-DD-YYY the date value will be translated as October 5, 2009.
- Any of the three separators will be valid for date entry but will be translated to the selected separator. For example, if you choose a format of MM/DD/YYY and the user enters 10-05-2009, the date will display 10/05/2009.
- Dates entered like Feb 3, 2001 will be translated into the specified format.
frevvo adjusts dates expressed with a two-digit year to be within 80 years before or 20 years after. For example, using a pattern of "MM/DD/YY" and the current date/time of Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only year strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one-digit string, a three- or more digit string, or a two-digit string that isn't all digits, is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC. frevvo will always format as 4 digit years.
The date will be converted to the standard xsd:date format of yyyy-mm-dd in the submissions XML document. Here is an example: <Order Date>2012-03-06</Order Date>. Refer to Viewing XML Documents for more details.
Rules can be applied to the Date control in all variations.
Time Format
The Time Format property applies to the Time control type. The default recommended format is "Automatic", which is a locale-specific time format. The designer has the option to set a particular time format independent of the locale by using the format field, but this is not recommended. Read this documentation for more information about time controls and internationalization.
If you keep the default "Automatic" format, you can enter data into a Time control using any of the formats shown in the table. The Time control will accept and display the values as shown:
The Time Format dropdown provides variations of military and standard time conventions, with either colon or period separators.
When the Time Format property is set to a specific format, time entries entered into the form are reformatted to match the selected format. For example, if you choose a military time format of hh:mm:ss and enter 2:00 PM the time value will display in the form as 14:00:00.
The time will be converted to the standard xsd:time format of hh:mm:ss in the submissions XML document. Here is an example: <Order Time>14:00:00</Order Time>. Refer to Viewing XML Documents for more details.
Rules can be applied to the Time control in all variations.
Date/Time Format
Date/Time controls display both the Date Format and Time Format dropdown menus in the properties panel. Rules can be applied to the Date control in all variations. There are some additional considerations for the Date/Time control:
When you enter a date in the date portion of the date/time control (or select the date with the date picker), it will automatically fill the time portion of the control with a value for 12:00 AM. The value displayed depends on the time format selected: For example:
Time Format Default Time Display hh:mm 00:00 hh:mm PM 12:00 AM hh:mm:ss 00:00:00 hh:mm:ss PM
12:00:00 AM
- The date picker is included in the date portion of the date/time control. You can hide/disable it by unchecking the Date Picker checkbox on the Style tab.
- You cannot enter a time value without a date value.
- The time input field cannot be labeled. It is recommended that the label for the date portion be descriptive enough to include the time portion. If the date and time labels over the appropriate input fields are required, two separate controls can be used or the label for the date portion can be extended over the time input field, as shown in the image below:
The local time will be converted to and saved in UTC format and the date will be converted to the standard xsd:datetime format of yyyy-mm-ddThh:mm:ssZ in the submission XML document. Here is an example: <OrderDate>2013-08-12T19:13:00Z</OrderDate>. Refer to Viewing XML Documents for more details.
Date and Time Format on Mobile Devices
Mobile devices support limited date, time, and date/time formats. For example, if you have a date control in your form formatted mm/dd/yyyy and you use that control name as a template in the Form Action Message, you will notice that the message displayed after submitting is in the correct format on desktop view, but changes to yyyy-mm-dd on the mobile view. This is expected and may vary by device and OS.
Similarly, if you have a date field with a default date in your form it must be formatted as YYYY-MM-DD in order for it to display correctly on mobile devices.
frevvo recommends enabling the date picker for forms that will be used on mobile devices to ensure the date is selected accurately.
Date Picker Property
To display the date picker, check the checkbox on the Style Property panel. If checked, you will see the date picker inside the date control and the date portion of the date/time input control. The Date Picker's large font makes it easy to see.
Clicking on the today link in the date picker brings you to the current date. If you are looking at another month and you click on the today link, the date picker will automatically bring you to the current month with today’s date highlighted(bold). Select the date to populate the field in your form/workflow. To close the Date Picker, click the close link.
Month and year menus facilitate quick navigation to earlier/later dates. For example, selecting a past date when entering a Date of Birth is much easier when utilizing the dropdown menus. When selecting a date in the past, select the year first.
The Date Picker described above only applies to the desktop view. Date and Date-Time controls on mobile devices display device specific date pickers.
Automatic Locale-Aware Format
frevvo supports localization from the browser's locale setting. frevvo will recognize the browser locale and alter displays and input formats as well as language according to the user's setting. Setting this preference is browser-specific. Refer to this website for information about language preferences and how to change those in a number of popular browsers.
Here is an image of Date/Time controls with the browser language set for German and the Date/Time controls set for Automatic. Notice the date format is DD.MM.YYYY and the time format is HH:MM:
Changing the Firefox browser language setting to Lithuanian displays the dates and times using the format YYYY-MM-DD and HH:MM respectively:
The automatic locale-specific formatting and parsing for date, time, and date/time controls can be configured by manually adding the following properties in the locale properties file:
Property Name | Purpose | Notes |
---|---|---|
frevvo.date.format | Allows the admin to configure the locale-specific format pattern for date controls and the date portion of date/time controls. If not set it falls back to the system default value for the locale as derived from the Java runtime. | See http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html for date and time formatting pattern rules. |
frevvo.time.format | Allows the admin to configure the locale-specific format pattern for time controls and the time portion of date/time controls. TIf not set it falls back to the system default value for the locale as derived from the Java runtime. | See http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html for date and time formatting pattern rules. |
For example, let's say you want to change the MM.DD.YYYY to display as "Day of the week, Month Day, year" in the German locale. Simply add the following to the ger locale file located in the WEB-INF/data/locale directory as explained above:
frevvo.date.format="EEE, MMM d, ''yy"
After replacing the /WEB-INF/data directory file with the updated one, the date will display as shown in the Firefox browser set for the German locale:
To translate AM and PM in time / date-time control formats, assign the value "h:mm a" to the frevvo.time.format property in the concerned locale file.
Date Picker
The Date picker will be automatically translated according to the browser locale. You can override the browser setting by adding the properties shown below to the locale file. This localization only applies to the date picker on the desktop as the native date picker will be shown on mobile devices. You can translate (locale-specific) month names and abbreviated day of week names (two characters). The days of the week will always be shown as Sunday through Saturday, left to right on the date picker. Only the Gregorian calendar system is supported.
To localize the date picker on the desktop, manually add the following properties in the appropriate locale properties file in the WEB-INF/data/locale directory as explained ServerCustomization.
Property Name | Purpose |
---|---|
frevvo.date.month.1 | Allows the admin to override the locale-specific short name for the 1st month of the year (January). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.2 | Allows the admin to override the locale-specific short name for the 2nd month of the year (February). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.3 | Allows the admin to override the locale-specific short name for the 3rd month of the year (March). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.4 | Allows the admin to override the locale-specific short name for the 4th month of the year (April). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.5 | Allows the admin to override the locale-specific short name for the 5th month of the year (May). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.6 | Allows the admin to override the locale-specific short name for the 6th month of the year (June). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.7 | Allows the admin to override the locale-specific short name for the 7th month of the year (July). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.8 | Allows the admin to override the locale-specific short name for the 8th month of the year (Aug). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.9 | Allows the admin to override the locale-specific short name for the 9th month of the year (Sept). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.10 | Allows the admin to override the locale-specific short name for the 10th month of the year (Oct). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.11 | Allows the admin to override the locale-specific short name for the 11th month of the year (Nov). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.month.12 | Allows the admin to override the locale-specific short name for the 12th month of the year (Dec). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.weekday.1 | Allows the admin to override the locale-specific short name for the 1st day of the week (Sunday). This overrides the system default value for the locale as derived from the Java runtime. |
frevvo.date.weekday.2 | Allows the admin to override the locale-specific short name for the 2nd day of the week (Monday). This overrides the system |