Date and time

Appfarm Create natively supports the storage of date and time values and provides tools to format, manipulate, and localize these values.

Datetime data type

Datetime is a built-in data type in Appfarm Create. Datetime values can be stored in objects or App variables in by adding a property with a data type of Datetime. The same data type is used for the Created Date and Updated Date properties, which are added by default to each object class.

Datetime values are always stored in UTC and conform to the ISO-8601 standard, with precision down to a millisecond. For example, if use Developer tools to inspect a data source, you will see datetime values in the following format: 2020-02-08T13:15:00.000Z.

Default behavior

If you display a datetime value in an app, for example by binding a datetime property to the value of a Text component, the stored UTC value will be converted to local time according to the user's time zone.

This time zone is set automatically from the user's device and stored in the built-in App variable App Time Zone. As you see from this link, you may override the App Time Zone with a single Update Object.

If you wish to override the default behavior and force a specific time zone you can use the Update object action node to update App variables and assign a specific time zone to the App Time Zone property. This would typically be run in an action triggered by the On app load event handler.

Services also behave in a similar way. A default time zone is set in Service settings but this can be overridden in a request sent to an endpoint.

Understanding UTC and time zones

You have a datetime property Order.Delivery Date. If you set Delivery Date to 14:00 on February 8th when using your app (from a computer in the time zone Europe/Oslo), this is stored as 2020-02-08T13:00:00.000Z in the database since Europe/Oslo is UTC+1 at winter time.

If you instead set Delivery Date to 14:00 on June 8th, this will be stored as 2020-06-08T12:00:00.000Z since at that point in time, Europe/Oslo is UTC+2 due to daylight saving time.

In both cases, if you display Order.Delivery Date using a Text component, and data bind the Value to Order.Delivery Date.Hour, it will display "14:00". As described above, this is because apps interpret datetime values stored in the database in the context of the app's current time zone, as stored in the App variable App Time Zone.

By default, datetime values display the date in the format set in the active language (see Localization below). You can also select a fragment of the datetime value to be output, with the following options:

• Day

• Day of Month (1-31)

• Day of Week (ISO, 1-7)

• Hour (0-23)

• Minute (0-59)

• Month (1-12)

• Month Name

• Second (0-59)

• Week Number (ISO)

• Year

For user entry of dates and times in the client, it is recommended to use the Date Picker component. The Date Picker is customized using your app's theme and ensures a consistent user experience.

The Text Edit component can also be used, with the appropriate Input Data Type selected (Date, Time, Date & Time), although this will leverage the native date picker controls in the user's browser.

Two default datetime values are available throughout Appfarm Create, Date Now and Date Today.

• Date Now returns the current datetime in UTC.

• Date Today returns the datetime in UTC that equates to midnight of the current day in the client's timezone.

Value processor

The Value processor can be applied to a datetime value in order to format and/or manipulate the value before it is displayed or stored. It is possible to chain multiple operations within the Value processor.

Formatting

To format a datetime value using the Value processor in Component properties, select a datetime property (not a fragment) or the built-in values Date Now or Date Today. Then, within the Value processor, you can add a Format operation. Choose from the list of pre-defined formats or set a custom format. To set a custom format use the tokens described in the Moment.js documentation.

The list of formats are as follows, with en-US locale examples. Note that the exact format of the output is determined by the active client language's Calendar Locale.

• Timestamp (ISO 8601) ("2020-02-08T13:15:09.356Z")

• Time ("1:15 PM")

• Short Date ("2/8/2022")

• Date ("February 8, 2022")

• Long Date ("February 8, 2022, 1:15 PM GMT+1")

• From Now (relative time from now: "a day ago", "in a week")

• To Now (reverse of From Now)

• Calendar Time ("Yesterday at 2:30 AM")

• Custom (use Moment.js tokens)

The formatted string will be returned by the Value processor.

Manipulation

Given a datetime value, the Value processor can add and subtract units and shift the date to the start or end of a unit of time.

To add to, or subtract from a date use the Add and Subtract operations. You can specify the following units:

• Years

• Quarters

• Months

• Weeks

• Days

• Hours

• Minutes

• Seconds

• Milliseconds

To shift a date to the start or end of a unit of time use the Start of and End of operations. This is useful for example if you want to return the 1st of the month for a given date. You can shift the date using the following units:

• Year

• Quarter

• Month

• Week (Monday-Sunday)

• Week (Locale dependent)

• Day

• Hour

• Minute

• Second

The resulting datetime value will be returned by the Value processor.

Function editor and Moment.js

To simplify working with dates in the function editor, the external date library Moment.js is available. When you're working within the function editor, add Moment.js from Libraries in the lower left-hand corner and it will be included as a function parameter. By default, the library is given the parameter name "moment" and you use this parameter name to work with your datetime variables.

Moment.js allows for extensive date formatting, manipulation, and querying. It is possible to perform all the same actions available in the Value processor and more. Moment also supports method chaining.

When using Moment.js in the Function editor to return a datetime datatype, you must make sure that a simple data type is returned. Returning moment() returns a Moment.js object, not a simple data type. Adding .toJSON() to the expression will convert the moment object to a JSON datetime (the format of Appfarm's datetime datatype). For example: Setting Activity.Due Date to 7 days from now may be done with the function return moment().add(7,'days').toJSON().

Note that return values from functions that use Moment.js can also go through the Value processor for formatting. Simply chain on .toJSON() to return a UTC adjusted value that the Value processor can interpret.

Refer to the Moment.js documentation for a full overview of the methods available. Below are a few examples that highlight how the library can be used in the function editor.

Moment.js examples

moment().toJSON();
// 2022-02-08T13:15:09.356Z

moment(myDate).format("dddd, MMMM Do YYYY, h:mm:ss a");
// "Sunday, February 14th 2010, 3:25:50 pm"

moment(myDate).format("[Today is] dddd"); 
// "Today is Sunday"

moment(myDate).add(7, 'days').toJSON();
// Calculate the date one week ahead and return as an ISO 8601 string, adjusted to UTC

moment('2010-10-20').isSame('2009-12-31', 'year');
// Check if two dates are the same, with optional granularity

Localization

The default formatting of a datetime value can be automatically localized by adjusting the settings under Internationalization.

For each language added to a solution you can select a Calendar Locale and Date Format.

• Calendar Locale is referenced when displaying datetime related strings, for example "Monday" and "February".

• Date Format is the default date format that will be applied when displaying a datetime value.

Below is an example of how the two settings work together to format dates:

Calendar Locale	Short Date	Date	Long Date
English - Great Britain	07/02/2022	7 February 2022	7 February 2022, 00:00 CET
English - United States	2/7/2022	February 7, 2022	February 7, 2022, 12:00 AM GMT+1
Norsk Bokmål	7.2.2022	7. februar 2022	7. februar 2022, 00:00 CET