--- category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend] keyword: [Extend, Presentation Components, widgets, tags, UI components] nav: wcp_docs parent_url: /wcp_docs/ title: date layout: subsection wd_wcptag: date --- Displays a date widget that opens a calendar. By default, the `date` widget displays dates in `MM/dd/yyyy` format. Use `date` on: - A view page when you want to display a date that users can't edit. A view page displays the `date` widget as a non-editable text field. - An edit page when you want to enable users to enter a date. An edit page displays the `date` widget with editable month, day, and year fields along with a calendar. The data type of the `date` widget value is Date, which includes the date, time, and time zone. For an empty value, set the value to null. Jump to: - [Examples](/wcp_docs/pha1517957224372.html#section-examples) - [Mobile Support](/wcp_docs/pha1517957224372.html#section-mobile-support) - [Attributes](/wcp_docs/pha1517957224372.html#section-attributes) - [PMD Scripting Methods](/wcp_docs/pha1517957224372.html#section-pmd-scripting-methods) - [PMD Scripting Events](/wcp_docs/pha1517957224372.html#section-pmd-scripting-events) ## Displaying Dates During page load, Presentation Components convert the input date string (such as the date string from an inbound endpoint) to a date object. The string-to-date conversion uses the `dateFormat` and `inputTimeZone` attributes to create the date object. On a view page, the `date` widget then uses the `dateDisplayPattern`, `datePrecision`, and `displayTimeZone` attributes to display the date object. On an edit page, the `date` widget uses the preferred display language of the user, `datePrecision`, and `displayTimeZone` attributes to display the date object. To control the display of the `date` widget, specify these attributes: - dateFormat If the format of the input date string is different from the default `yyyy-MM-dd HH:mm:ss.SSS`, specify `dateFormat`. The `dateFormat` attribute instructs the `date` widget how to convert the input string to a date object. Note: The model component REST APIs use the date format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. If the `dateFormat` doesn't match the actual date format of the input string, the `date` widget displays empty. - inputTimeZone If the timezone for the input date string is different from the default UTC timezone, specify `inputTimeZone`. The `inputTimeZone` attribute specifies the timezone used to convert the input date string to a date object. - dateDisplayPattern The format for displaying the date on view pages. Note: An edit page uses the preferred display language of the signed-in user to determine the display format of the date widget. An edit page ignores the `dateDisplayPattern` attribute. The default display pattern is `MM/dd/yyyy`. If you specify the time precision in `datePrecision`, the default display pattern is `MM/dd/yyyy hh:mm:ss AM/PM`. - displayTimeZone The time zone used for displaying the time on the date widget. The default display timezone is UTC. You can use the `userTimeZone` predefined app variable to get the timezone of the currently signed-in user. - datePrecision The precision (year, month, day, hour, minute, second, millisecond) of the date display. To display the time on the `date` widget, set `datePrecision` to HOUR, MINUTE, SECOND, or MILLISECOND. If you don't specify `datePrecision`, the `date` widget displays the day in `MM/dd/yyyy` format. If you include the time in `dateDisplayPattern` on a view page, the `date` widget displays the time as 12:00 AM. Example: Given the current date and time in Bangkok, this sample displays the date and time using a custom display pattern in the Asia/Bangkok timezone. Note that because the input timezone is different from UTC, this example includes both `displayTimeZone` and `inputTimeZone`: ``` { "type": "date", "dateDisplayPattern": "MM-dd-yyyy hh:mm a z", "datePrecision": "SECOND", "displayTimeZone": "Asia/Bangkok", "inputTimeZone": "Asia/Bangkok", "value": "<% date:getTodaysDate(date:getDateTimeZone('Asia/Bangkok')) %>" } ``` Sample result on a view page: ![](GUID-6e10308c-9497-4917-91ea-5cfe5ff5dbeb-enHYPHENus.png) Sample result on an edit page: ![](GUID-07a143de-e56f-4612-8cc6-fc5dfa67eb20-enHYPHENus.png) For more `date` examples on view and edit pages, see [Examples](/wcp_docs/pha1517957224372.html#section-examples). ## Submitting Dates To submit the value of a `date` widget to the outbound endpoint, format the outbound date value using 1 of these `date` PMD functions: - `format(date, dateFormat)` - Specify the outbound date format in the default UTC timezone. Use this function if the persisted date must be in the UTC timezone. Example: ``` "valuesOut": [ { "value": "<% self.value.format('yyyy-MM-dd') %>", "valueOutBinding": "postExpense.date" } ] ``` - `formatWithTimeZone(date, dateFormat, timeZone)` - Specify the outbound date format in a given timezone. Use this function if the persisted date must be in a non-UTC timezone. Example: ``` "valuesOut": [ { "value": "<% self.value.formatWithTimeZone('yyyy-MM-dd\\'T\\'HH:mm:ss.SSS\\'Z\\'', 'US/Eastern') %>", "valueOutBinding": "myBusinessObject.submittedDate" } ] ``` For `date` examples on edit pages, see [Examples](/wcp_docs/pha1517957224372.html#section-examples). ## Localizing Date Formats To localize the `date` widget to the preferred display language of the signed-in user, add the language code of the preferred display language in `languages[]` in the Site Metadata (SMD). Example: If users set the preferred display language in Workday to Netherlands, add `nl-NL` to `languages[]` in the SMD: ``` "languages": [ { "code": "en-US", "description": "English" }, { "code": "nl-NL", "description": "Dutch (Netherlands)" } ] ``` When the user runs the app, the `date` widget automatically displays the date format using the preferred display language. This sample date (from previous example, checkInDateTime) displays the 12/22/2021 04:16:59 date and time in the `dd-MM-yyyy HH:mm:ss` format. ![](GUID-1853361a-fe05-4abe-b725-d1886718d1ab-enHYPHENus.png) Note: The sample label uses a label translation key: ``` "label": "<% presentationLabels.checkInDate %>" ``` For details about translating labels, see [Translate Widgets Using the Workday Extend Plugin for IntelliJ](/wcp_docs/asf1579369476848.html). ## Examples View page examples This sample displays the current date and time in the user timezone (Example: US/Pacific) using the default display pattern: ``` { "type": "date", "datePrecision": "SECOND", "label": "Current date and time in my timezone:", "value": "<% date:getTodaysDate(date:getDateTimeZone(userTimeZone)) %>" } ``` Sample result: 12/21/2021 6:27:46 PM Given the current date and time in Toronto, this sample displays the date and time using a custom display pattern in the America/Toronto timezone. Note that because the input timezone is different from UTC, this example includes both `displayTimeZone` and `inputTimeZone`: ``` { "type": "date", "dateDisplayPattern": "yyyy-MM-dd hh:mm:ss a z", "datePrecision": "SECOND", "displayTimeZone": "America/Toronto", "inputTimeZone": "America/Toronto", "label": "Current date and time in Toronto", "value": "<% date:getTodaysDate(date:getDateTimeZone('America/Toronto')) %>" } ``` Sample result: 2021-12-21 06:27:46 PM EST This sample displays a date retrieved from a model business object using the default display pattern `MM/dd/yyyy` and the default day `datePrecision`. In this example, the submittedDate value is 2021-01-31T16:05:33.000Z. ``` { "type": "date", "label": "submittedDate using the default pattern and precision:", "value": "<% myBusinessObject.data[0].submittedDate %>" } ``` Sample result: 01/31/2021 This sample displays a date retrieved from a model business object using the default `MM/dd/yyyy hh:mm:ss AM/PM` pattern. In this example, the submittedDate value is 2021-01-31T16:05:33.000Z. We specify `dateFormat` because the time portion in the business object date is different from the default `yyyy-MM-dd HH:mm:ss.SSS`. ``` { "type": "date", "label": "submittedDate and time using the default pattern with time:", "datePrecision": "SECOND", "dateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", "value": "<% myBusinessObject.data[0].submittedDate %>" } ``` Sample result: 01/31/2021 4:05:33 PM This sample displays a date retrieved from a model business object using a date display pattern. In this example, the submittedDate value is 2021-01-31T16:05:33.000Z. ``` { "type": "date", "label": "submittedDate and time using a custom display pattern:", "dateDisplayPattern": "EEE, MMM d, ''yy 'at' hh:mm:ss a z", "dateFormat": "yyyy-MM-dd'T'HH:mm:ss", "value": "<% myBusinessObject.data[0].submittedDate %>" } ``` Sample result: Sun, Jan 31, '21 at 04:05:33 PM UTC This sample displays a date retrieved from a model business object using a date display pattern in a specific timezone. In this example, the submittedDate value is 2021-01-31T16:05:33.000Z ``` { "type": "date", "label": "submittedDate and time using a custom display pattern and timezone:", "dateDisplayPattern": "EEE, MMM d, ''yy 'at' hh:mm:ss a z", "displayTimeZone": "America/Los_Angeles", "dateFormat": "yyyy-MM-dd'T'HH:mm:ss", "value": "<% myBusinessObject.data[0].submittedDate %>" } ``` Sample result: Sun, Jan 31, '21 at 08:05:33 AM PST Edit page examples This sample displays the current date and time in the user timezone, and sends the submitted date of a model business object. It doesn't specify `dateFormat` because the input date (from `date:getTodaysDate`) already uses the default `yyyy-MM-dd HH:mm:ss.SSS`. The `valuesOut` value uses the `format` date function to specify the outbound date format in the default UTC timezone. ``` { "type": "date", "id": "checkInDateTime", "label": "Check In Date and Time", "datePrecision": "SECOND", "displayTimeZone": "<% userTimeZone %>", "inputTimeZone": "<% userTimeZone %>", "required": true, "value": "<% date:getTodaysDate(date:getDateTimeZone(userTimeZone)) %>", "valuesOut": [ { "value": "<% self.value.format('yyyy-MM-dd\\'T\\'HH:mm:ss.SSS\\'Z\\'') %>", "valueOutBinding": "postBusinessObject1.submittedDate" } ] } ``` Sample date widget showing current date and time in US/Pacific timezone: ![](GUID-05673e1f-5e32-4241-9acf-2b41c6251d21-enHYPHENus.png) Sample result data with the submitted date in the UTC timezone: ``` { "id": "ba582f14c92781001993d4699c540000", "descriptor": "MLC Date", "submittedDate": "2021-12-23T00:16:59.000Z" } ``` Given a business object date in UTC, this next sample displays the date and time in the user timezone, and sends the submitted date in the US/Eastern timezone. It specifies `dateFormat` because the time portion of the business object date is different from the default `yyyy-MM-dd HH:mm:ss.SSS`. The `valuesOut` value uses the `formatWithTimeZone` date function to specify the outbound date format in the US/Eastern timezone. Note: Workday recommends that you store datetimes in the UTC timezone. This example stores the datetime in a different timezone only for illustration purposes. ``` { "type": "date", "id": "firstSubmittedDate", "label": "Submission Date and Time", "datePrecision": "SECOND", "dateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", "displayTimeZone": "<% userTimeZone %>", "inputTimeZone": "<% userTimeZone %>", "required": true, "value": "<% myBusinessObject.data[0].submittedDate %>", "valuesOut": [ { "value": "<% self.value.formatWithTimeZone('yyyy-MM-dd\\'T\\'HH:mm:ss.SSS\\'Z\\'', 'US/Eastern') %>", "valueOutBinding": "postBusinessObject2.submittedDate" } ] } ``` Sample date widget displays the inbound submittedDate 2021-01-31T16:05:33.000Z in US/Pacific timezone: ![](GUID-b109e475-0389-4213-a9a1-f01d2d192bbd-enHYPHENus.png) Sample result data with the submitted date in US/Eastern timezone: ``` { "id": "ba582f14c92781001993e236237a0000", "descriptor": "MLC Date", "submittedDate": "2021-01-31T11:05:33.000Z" } ``` This next example displays a date widget in a grid. The date widget uses the default date format and timezone, and uses the `format` function to send the outbound date to the Workday Expense endpoint. ``` { "type": "column", "columnId": "dateDateColumm", "label": "Date", "cellTemplate": { "type": "date", "id": "expenseDateDate", "value": "<% rowdata.date ?? pageVariables.defaultDate %>", "valuesOut": [ { "value": "<% self.value.format('yyyy-MM-dd') %>", "valueOutBinding": "postExpense.date" } ] } } ``` Sample date widget in a grid column using default day precision and format: ![](GUID-4b16a66d-c58e-4e59-b619-950a6645d4ff-enHYPHENus.png) Sample result data with the expense date in default date format: ``` { "descriptor":"12/22/2021 Default memo 0.00 USD", "id":"ba582f14c9270100163cd45e57800000", "date":"2021-12-22", . . . } ``` ## Dates in Sample Apps You can look at how the `date` tag is used with date functions in these sample apps in the [App Catalog](https://developer.workday.com/app-catalog): - Work From Almost Anywhere: The `dates.script` contains several date calculation functions. - Project Forecasting: The `dates.script` contains several data formatting functions. - PMD Scripting: The `dataCalculations.pmd` contains examples of the `onChange` event on the `date` widget. ## Mobile Support Android, iOS ## Attributes - dateDisplayPattern Data type: binding-String Defines the format for displaying the date. For valid date formats, see the Java documentation for `java.text.SimpleDateFormat`. Note: This attribute overrides the user locale setting. - dateFormat Data type: binding-String Specifies the date format for reading an inbound date field. Default format: `yyyy-MM-dd HH:mm:ss.SSS`. For valid date formats, see the Java documentation for `java.text.SimpleDateFormat`. Date fields from Workday REST APIs can either be datetimes or dates. Datetimes use the ISO 8601 format. Example: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. Dates have no time component and use the format `yyyy-MM-dd`. - datePrecision Data type: string Specifies how precise you want to format a date. Available values include: - YEAR - MONTH - DAY (default) - HOUR - MINUTE - SECOND - MILLISECOND - displayTimeZone Data type: binding-String Applies the time zone when a date displays. You can use the [getDateTimeZone (timeZone)](/wcp_docs/ipy1526018844612.html) with this attribute. This sample uses the `userTimeZone` predefined app variable to get the timezone of the currently signed-in user: ``` "displayTimeZone": "<% userTimeZone %>" ``` - enabled Data type: dynamicBinding-Boolean If true, users can enter values on the widget. If false, users can only view the widget. - guide Data type: `guide` Displays a ? widget that opens a popup window containing guidance information about a widget on an edit page. For details, see the `guide` tag. - helpText Data type: binding-String Text that displays when a user hovers their cursor over the widget. Note: The Chrome browser truncates the tooltip to 1400 characters. - id Data type: binding-String Unique identifier used to reference this widget from other tags. Notes: - The `id` must start with a letter. - The `id` must be unique per page. - To enable other widgets to reference this widget `id`, place this widget before the other widgets on the PMD. The PMD validation returns an "Undefined variable" error if it doesn't find a previously defined `id` in the PMD. - Workday recommends that you include the `id` in your tag definitions for debugging purposes. - inputTimeZone Data type: binding-String Specifies the time zone for dates and times in incoming data. You can use the date:getDateTimeZone() function with this attribute. This sample uses the `userTimeZone` predefined app variable to get the timezone of the currently signed-in user: ``` "inputTimeZone": "<% userTimeZone %>" ``` - label Data type: dynamicBinding-String Text that displays beside or above most widgets. Often used in simple widgets that include inputs. The maximum number of characters is 255. - render Data type: binding-Boolean If true, this tag renders as a widget on the page. If false, the loaded page doesn't add this tag or its children. The default is true. Unlike the `visible` attribute, when `render` is false, other tags on the page can't reference this tag or widget on edit pages. On view pages, a tag can't reference other tags regardless of the `render` attribute value. - required Data type: dynamicBinding-Boolean If true, the user must enter a value on the widget before submitting the page. - sortOrder Data type: binding-String When you set `sorted` to true on the `section` or `fieldSet` parent of this widget, the `sortOrder` attribute determines the order of this widget within its parent. The sort order is relative to the siblings of the widget. Typical values are "a", "b", "c", and so on. Example: The widget with `"sortOrder": "a"` displays before the widget with `"sortOrder": "b"`. Note: The `sortOrder` doesn't apply to sorting data on the widget. `sortOrder` only applies to the placement order of the widgets within the parent widget. - value Data type: dynamicBinding-String The displayed value when the page renders. Users can change this value on edit pages. Example: You can set the `value` attribute to a value from an inbound endpoint, script, or any app variable (such as queryParams.someVariable). The page displays the initial value when the page loads. When the user changes this value on an edit page, it sends the `value` with `valueOutBinding` as the JSON field binding in the outbound request payload. Note: If you're using `valuesOut` instead of `valueOutBinding` as a root-level attribute, the root-level `value` is the inbound value for the page load while the `value` in `valuesOut` corresponds to the outbound value sent with the `valueOutBinding`. - valueOutBinding Data type: dynamicBinding-String A binding to the JSON field that stores the date value in the outbound request payload. To store the time portion or a formatted date, use the `valuesOut` attribute instead. Note: If the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the widget's `valueOutBinding` data in the outbound payload. To include the `valueOutBinding` data in the payload, use the `onSend` event handler. - valuesOut Data type: list of outValue objects An array of values and their bindings to JSON fields in the outbound request payload. An array item consists of these attributes: - `value` - An object binding of the value to include in the outbound JSON. - `valueOutBinding` - A string binding of the JSON field that contains the value in the request payload. We send the request payload with the outbound endpoint when the user submits the page. You can use `valuesOut[]` to: - Convert a date to a specific format. - Store the time portion of the date widget. This example uses PMD functions to extract the year and month from date values, and sends them separately to the outbound endpoint: ``` "valuesOut": [ { "value": "<% date:month(date1.value) %>", "valueOutBinding": "anOutboundEndpoint.dateMonth" }, { "value": "<% string:toString(date:year(panelList1Date1.value)) %>", "valueOutBinding": "anOutboundEndpoint.dateYear" }, { "value": "<% date:format(self.value, 'yyyy-MM-dd\\'T\\'HH:mm:ss') %>", "valueOutBinding": "anOutboundEndpoint.dateTime" } ] ``` Note: If the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the widget's `valuesOut` data in the outbound payload. To include the `valuesOut` data in the payload, use the `onSend` event handler. - visible Data type: dynamicBinding-Boolean If true, the widget generated by this tag is visible. If false, this tag and its children tags aren't visible. This tag provides the ability to display or hide the widget dynamically based on user interactions on the page. The default is true. Unlike the `render` attribute, the generated widget persists on the page even when `visible` is false. Notes: - When the widget or field you’re hiding changes on the page, you must include it inside a `fieldSet`. - When the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the `valueOutBinding` or `valuesOut` data of the widget in the payload. To include the `valueOutBinding` or `valuesOut` data in the payload, use the `onSend` event handler. ## PMD Scripting Events - onChange Triggers when the user changes the value of the widget. ## PMD Scripting Methods - clearError() Return type: `void` Description: Clears the validation error. - clearWarning() Return type: `void` Description: Clears the validation warning. - getLabel() Return type: `string` Description: Returns the widget label. - getValue() Return type: `Object` Description: Returns the value of this widget. - getValueOutBinding() Return type: `string` Description: Returns the outbound value binding of this widget. - isEnabled() Return type: `boolean` Description: Returns true if this widget is enabled. - isRequired() Return type: `boolean` Description: Returns true if this widget is required. - isUpdated() Return type: `boolean` Description: If true, this widget is manually updated by the end-user. - isUpdatedByScript() Return type: `boolean` Description: If true, this widget is programmatically updated by a PMD script. - isVisible() Return type: `boolean` Description: Returns true if this widget is visible. - setEnabled(boolean enabled) Return type: `void` Description: Enables or disables this widget. - setError(String error) Return type: `void` Description: Sets the validation error. The input error message displays in the page error window. - setLabel(String label) Return type: `void` Description: Sets the widget label. - setRequired(boolean required) Return type: `void` Description: Makes this widget required or not required. - setValue(Object value) Return type: `void` Description: Sets the value of this widget. For `date` widgets: When you set the value of a `date` widget to an empty value, specify `null` instead of an empty string. Example: `dateWidgetId.setValue(null)` or `dateWidgetId.value = null`. - setValueOutBinding(String valueOutBinding) Return type: `void` Description: Sets the outbound value binding to this widget. - setVisible(boolean visible) Return type: `void` Description: Displays or hides this widget. If you need to change the visibility of a widget, ensure that it's inside a `fieldSet`. - setWarning(String warning) Return type: `void` Description: Sets the validation warning. ### Related Information [Java DateFormatter: Patterns for Formatting and Parsing](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html)