# 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](https://docs.appfarm.io/data-model/object-classes#data-types) in Appfarm Create. Datetime values can be stored in [objects](https://docs.appfarm.io/reference/platform-concepts/objects) or [App variables](https://docs.appfarm.io/reference/apps/data/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](https://docs.appfarm.io/reference/data-model/object-classes). Datetime values are always stored in UTC and conform to the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601), with precision down to a millisecond. For example, if use [Developer tools](https://docs.appfarm.io/reference/appfarm-client/developer-tools-for-apps) 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](https://docs.appfarm.io/reference/platform-concepts/data-bindings) a datetime property to the value of a [Text component](https://docs.appfarm.io/library/ui-components/text), 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](https://docs.appfarm.io/apps/data/app-variables#built-in-app-variables) **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](https://docs.appfarm.io/library/action-nodes/update-object) to update [App variables](https://docs.appfarm.io/reference/apps/data/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](https://docs.appfarm.io/apps/app-settings#event-handlers). [Services](https://docs.appfarm.io/reference/services) also behave in a similar way. A default time zone is set in [Service settings](https://docs.appfarm.io/reference/services/service-settings) but this can be overridden in a request sent to an [endpoint](https://docs.appfarm.io/reference/services/service-endpoints). {% tabs %} {% tab title="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](https://docs.appfarm.io/library/ui-components/text), and [data bind](https://docs.appfarm.io/reference/platform-concepts/data-bindings) 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](https://docs.appfarm.io/apps/data/app-variables#built-in-app-variables) **App Time Zone**. {% endtab %} {% endtabs %} By default, datetime values display the date in the format set in the active language (see [Localization](#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](https://docs.appfarm.io/reference/platform-concepts/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](https://docs.appfarm.io/reference/apps/ui/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](https://momentjs.com/docs/#/displaying/format/). 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](https://momentjs.com/docs/#/displaying/format/)) 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](https://docs.appfarm.io/reference/platform-concepts/functions) 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](https://momentjs.com/docs/) 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. {% code title="Moment.js examples" %} ```javascript 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 ``` {% endcode %} ## Localization The default formatting of a datetime value can be automatically localized by adjusting the settings under [Internationalization](https://docs.appfarm.io/reference/resources/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 LocaleShort DateDateLong Date
English - Great Britain07/02/20227 February 20227 February 2022, 00:00 CET
English - United States2/7/2022February 7, 2022February 7, 2022, 12:00 AM GMT+1
Norsk Bokmål7.2.20227. februar 20227. februar 2022, 00:00 CET