Merge pull request mendix#6485 from jveldhuizen/patch-1

Add information about date time functions and tokens in combination with non-localized attributes

Author: Yiyun333

content/en/docs/refguide/modeling/application-logic/expressions/date-creation.md

@@ -9,6 +9,10 @@ tags: ["studio pro", "expression", "date creation", "expressions"]
 
 Dates can be created with the `dateTime` and `dateTimeUTC` functions. The difference between them is that  `dateTime` uses the calendar of the session used in the function call, and `dateTimeUTC` uses the UTC calendar. The system session runs as UTC by default, except for scheduled events, which can be configured in the [Scheduled Event Time Zone](/refguide/app-settings/#scheduled) section of **App Settings**.
 
+{{% alert color="info" %}}
+Do not use `dateTimeUTC` in client-side expressions (for example, in nanoflows) if you want to assign the output to (or compare the output with) an attribute of type **Date and time** where **Localize** is disabled. In the client, the localization functionality is built into the attribute type itself, and using UTC functions causes the time zone conversion to be handled twice.
+{{% /alert %}}
+
 This function does not accept variable or attribute parameters, only fixed values. To create a date using parameters, use the [parseDateTime](/refguide/parse-and-format-date-function-calls/#parsedatetime-utc) function.
 
 ## 2 Values

content/en/docs/refguide/modeling/application-logic/expressions/parse-and-format-date-function-calls.md

@@ -53,6 +53,10 @@ The following pattern letters are only available for microflows:
 | Z      | Time zone                                 | -0800                                 |
 | X      | Time zone                                 | -08; -0800; -08:00                    |
 
+{{% alert color="info" %}}
+For some parse and format functions, there are UTC variants. Do not use these UTC variants (for example, `parseDateTimeUTC`) in client-side expressions if you want to assign the output to (or compare the output with) an attribute of type **Date and time** where **Localize** is disabled. In the client, the localization functionality is built into the attribute type itself, and using UTC functions causes the time zone conversion to be handled twice.
+{{% /alert %}}
+
 ## 2 parseDateTime[UTC] {#parsedatetime-utc}
 
 Takes a string and parses it. If it fails and a default value is specified, it returns the default value. Otherwise, an error occurs. The function `parseDateTime` uses the user's time zone and `parseDateTimeUTC` uses the UTC calendar.

content/en/docs/refguide/modeling/domain-model/entities/attributes.md

@@ -124,17 +124,17 @@ A customer can be active or inactive, which is stored in an attribute named **Ac
 
 {{< figure src="/attachments/refguide/modeling/domain-model/entities/attributes/customer-attribute-examples.png" >}}
 
-#### 2.2.2 Localize
+#### 2.2.2 Localize {#localize}
 
 {{% alert color="info" %}}
 This property is shown if **Type** is set to **Date and time**.
 {{% /alert %}}
 
-This property indicates whether the date and time should be localized. By default localization is enabled. If you are *not* interested in the time component of a date (for example, a birthday), you should set this property to 'No'. Otherwise, the date can change because of time zone differences: a date and time early in the morning on April 2nd in Europe will be on April 1st in the U.S.A.
+This property indicates whether the date and time should be localized when displaying (or picking) their value. By default localization is enabled. If you are NOT interested in the time component of a date and you want the date to be exactly the same all over the world (for example, a birthday), you should toggle this property off. Otherwise, the date can change because of time zone differences: a date and time early in the morning on April 2 in Europe will be on April 1 in the U.S.A.
 
-In technical terms, this property indicates whether the client assumes that the date and time are in a local time zone (Yes) or in UTC (No). In the former case, the date is first converted to UTC before being sent to the server and converted from UTC before being displayed.
+In technical terms, this property indicates whether the client assumes that the date and time are in a local time zone (enabled) or in UTC (disabled). In the former case, the date is first converted to UTC before being sent to the server and converted from UTC before being displayed. To avoid this time zone conversion from happening twice, UTC functions and tokens like [dateTimeUTC](/refguide/date-creation/) should not be used in client-side expressions to assign values to **Date and time** attributes where localization is disabled.
 
-Default: *Yes*
+Default: *enabled*
 
 #### 2.2.3 Enumeration
 

content/en/docs/refguide/modeling/xpath/xpath-constraints/xpath-keywords-and-system-variables.md

@@ -94,6 +94,10 @@ The following tokens can be used to obtain a date and time value:
 | `[%EndOfCurrentYear%]` | The date and time at the end of the current year. |
 | `[%EndOfCurrentYearUTC%]` | The date and time at the end of the current year in UTC. |
 
+{{% alert color="info" %}}
+Do not use the UTC variants of these tokens (for example, `[%BeginOfCurrentDayUTC%]`) in client-side expressions if you want to assign the output to (or compare the output with) an attribute of type **Date and time** where **Localize** is disabled. In the client, the localization functionality is built into the attribute type itself, and using UTC functions causes the time zone conversion to be handled twice.
+{{% /alert %}}
+
 The following tokens can be used to add or subtract a period of time from a date and time token value:
 
 | Token | Description |

content/en/docs/refguide/runtime/date-and-time-handling/_index.md

@@ -63,9 +63,9 @@ If your application is accessible without signing in, those anonymous users will
 
 ## 6 To Localize or Not to Localize
 
-Per attribute of type **Date and time** you can specify whether you want the date and time to be localized. This is not a new feature but worth mentioning on this page. Both localized and non-localized attributes are stored in UTC but only localized attributes are converted to the time zone of the user when displaying their value. Use non-localized attributes if you are not interested in the time component (for example, birthdays) or if you want a date to look exactly the same all over the world.
+Per attribute of type **Date and time** you can specify whether you want the date and time to be localized when displaying (or picking) their value. This is not a new feature but worth mentioning on this page. Both localized and non-localized attributes are stored in UTC but only localized attributes are converted to the time zone of the user when displaying their value (for example, in the client or in generated documents). Use non-localized attributes if you are not interested in the time component of a date and you want the date to be exactly the same all over the world (for example, a birthday).
 
-See the documentation of the Localize property of [Attributes](/refguide/attributes/) for more information.
+For more information, see the [Localize](/refguide/attributes/#localize) section in *Attributes*.
 
 ## 7 Tokens