Setting the Date Format Based on the User's Locale

Description

The date and time format can be dynamically set using the culture code on the user's device. The day and month names can also be dynamically changed based on device locale settings.

Discussion

You can specify that the date format, day names and month names for a Grid and UX component should be automatically selected based on the 'Accept-language' property in the request header when the browser makes a request. This makes it easier to build applications that seamlessly adapt based on the user's locale setting.

To use locale settings, set the Date format to:

<cultureDateFormat>

If you also want to include time in the format, you can use the following:

<cultureDateFormat> <cultureTimeFormat>

You can also configure the day and month names to use the user's locale.

To use day names based on the user's locale, set the Date picker - day names property to:

<cultureDayNames>

To use month names based on the user's locale, set the Date picker - month names property to:

<cultureMonthNames>

The Date format property also controls how date and datetime values are displayed in data-bound controls, not just how users enter values. This applies to UX controls (including List and ViewBox) and Grid components.

Previously, display format was determined by the server's regional settings. Now, the Date format property takes priority.

This makes it easier to build international applications without manually setting format strings for each control.

For example, if the server's regional setting uses MM/dd/yyyy, but you set the Date format to dd.MM.yyyy, all bound controls and lists will now display dates using dd.MM.yyyy.

With v4.6.4.7, when you set the Date format property for dates to:

<cultureDateFormat>

the Simulated culture property is displayed. This allows you easily test how dates and times will be rendered in different cultures.

Change in behavior with v4.6.4.7:

UX and Grid Components - Date Format property - Previously, the Date Format property in UX and Grid properties was used to control how the user was expected to enter date/datetime values (and also to control how the Date Picker returned values if the format for the Date Picker had been set to <Default>). The default display format for date/datetime values was determined by the regional settings on the server.

Now, the Date Format property in UX/Grid properties controls both how the user is expected to enter date values, but also how data bound UX controls (including List and ViewBox controls) and Grid components will display date and datetime values.

An example of how this will work from now on is: if the regional settings on your server are configured to render dates in MM/dd/yyyy format (i.e. US format) and the Date Format property in a UX component is set to dd.MM.yyyy, then assuming the UX is data bound, any control that displays date or datetime values will use the dd.MM.yyyy format (because that is the format that is set in the Date Format property). In addition, List and ViewBox controls that display date or datetime values will use the dd.MM.yyyy format for the date part (again, because that is the setting for the Date Format property).

Previously, the data would have been displayed in MM/dd/yyyy format because that is the format of dates on the server.

The benefit of this change in behavior is that it is now easier to create applications that deal with date and datetime values in a more intuitive manner.

For example, say you have an app that is hosted on Alpha Cloud. The server format for dates on Alpha Cloud is MM/dd/yyyy. This means that if a developer is hosting their app on Alpha Cloud, date and datetime values in the application would by default be displayed in MM/dd/yyyy format. Any user of this app who was outside the US would likely expect the date and datetime values to be formatted in dd/MM/yyyy format.

This is now easily achieved by setting the Date Format property in the Grid or UX to <cultureDateFormat> (and if you also want to display dates with time values, set the time part of the Date Format to <cultureTimeFormat>).

When a user in (say) the UK accesses this app, dates will be displayed in dd/MM/yyyy format (because the browser will automatically tell the server what culture to use). Similarly, when a user in the US accesses the same app, dates will be displayed in MM/dd/yyyy format (because that is the format for dates if the culture is US).

During development, the developer might want to know how dates will be rendered for users in any particular culture. If the Date Format is set to cultureDateFormat, a new property is displayed (Simulated culture). This allows you to simulate any culture.

This change will also affect the behavior of the .getValue() method in a UX component when getting the value in a textbox control that is configured to have a date picker, where the textbox datatype is "D" or "T" and the date format on the textbox date picker does not match the date format set in the UX's Date Format property (an illogical setting, but nevertheless, possible). Previously the .getValue() method would return the actual value in the textbox. Now, the .getValue() method will return a data value formatted according to the UX's Date Format property.

See Also

• Supporting Device Culture Codes
• UX Component Properties
• Grid Component Properties
• List Control
• ViewBox Control
• .getValue() Method
• Simulated Culture