Administrator Help

Open topic with navigation

Field Formatting

The Field Formatting feature enables you to configure how dates, times, and numbers are formatted in the site's viewers. Field formatting ensures that data is displayed to end users using the format that you specified, localized to the user's locale. Essentials supports a number of common, predefined formats, as well as custom formats.

If you use the viewer's locale parameter in viewer launch URLs, it will override the user's locale, which is used to localize dates, times, and numbers in the viewer. All dates, times, and numbers will be in the locale that is specified in the URL parameter. For more information, see URL Parameters Reference.

Background

There are many different formats that can be used for presenting dates, times, and numbers. Different locales use different conventions. For example, the USA uses a period as the decimal mark and commas to group the digits in large numbers—12,345,678.9—whereas the Netherlands uses a comma as the decimal mark and periods to group digits—12.345.678,9. Similarly, USA dates are written in month, day, year order and time is written using the 12-hour clock—10/20/2015 8:45:07 PM—whereas in the Netherlands, dates are written in day, month, year order and time is written using the 24-hour clock—20-10-2015 20:45:07.

Within a particular locale, there are options for how dates, times, and numbers can be formatted. For example, you might want to write out the month—October 20, 2015 in the USA or 20 oktober 2015 in the Netherlands—or you might want to present numeric data as currency—$12,345,678.90 in the USA or US$12.345.678,90 in the Netherlands.

In some situations, the choice of formatting reflects what is significant in the context. For example, an application that maps major earthquakes through the ages might omit the day and time from dates—Oct. 1707 in the USA or okt. 1707 in the Netherlands.

Contexts Where Field Formatting Applies

Field formatting is applied to feature data, data from data links, and data from ArcGIS tables. It applies to nearly all contexts, for example, search and identify results, measurements, map tips, and feature details.

There are a few contexts in which viewers do not apply the formatting:

• Exported Data: When an end user exports data to an Excel spreadsheet, comma-delimited (CSV) file, or shapefile, the full data is exported in a standard format. Exported dates follow the ISO 8601 standard. Numbers are exported to the full precision of the stored data, using periods as the decimal marker, for example, 91623.1534.

• Edited Data: When an end user clicks in a numeric or date field to edit the value, the viewer removes the field formatting and displays the full, stored value. The user can enter values with more decimal places than the viewer displays, and the full value is stored. For example, a user could enter 0.4871 in a field that is formatted to display one decimal digit.

• Reports: The date/time and number formatting that you configure in Manager do not affect how data is presented in reports.

• Charts: Charts have their own settings for formatting dates and numbers in the X-axis and Y-axis. See Category Setup (Horizontal Axis) and Series Setup (Vertical Axis) for information.

• GeoRSS Layers: Viewers cannot apply field formatting to GeoRSS layers, because GeoRSS layers do not provide information about the type of data that a field contains.

Field formatting also applies to contexts in which users enter values, such as Global Search, Query Builder, and workflow forms. The viewer assumes that values entered by the user are in the notation of the user's locale. For example, a viewer would interpret 8-11-2015 as August 11, 2015 in locales that place the month before the day, or as November 8, 2015 in locales that place the day first.

Interpretation of numeric data also depends on the locale. For example, suppose a user in the Netherlands is looking at land values in the USA. The user creates a query in Query Builder to search for parcels valued at less than ninety-two thousand dollars. The user enters value < 92.000. Because the user's locale is nl-NL, the viewer interprets the value as ninety-two thousand, not ninety-two point zero zero zero.

If the viewer cannot interpret the value in the user's locale, the viewer tries to interpret it in en-US notation. For example, if the user enters value < 92,000.00, the viewer would not be able to interpret the value in the standard nl-NL notation, so the viewer would interpret it in en-US notation (the "invariant" location).

About Configuring Field Formats

You can configure date/time and number formats at the map service level, the layer level, and the field level. By default, formatting is inherited from a higher level—fields inherit their formatting from the layer, and layers inherit their formatting from the map service.

You can use inheritance to reduce the amount of configuration you have to do. For example, suppose you have a Parcels layer with several fields related to the parcel's value—the assessed value, value of improvements, value at which the parcel last sold, and so on. Instead of configuring each field individually, you could configure the layer to use Currency formatting and let the fields inherit the formatting.

Initially, the formatting for map services, layers, and fields is set to Default, which inherits the formatting from a higher level. You can override inherited values by configuring a particular format at a lower level. For example, you could set a date format for a map service, but override it for a particular layer within the map service, and override it again for a particular date field in the layer.

If you leave the format for a field, its layer, and its map service all set to Default, the viewer uses the Fixed-point format with up to four decimal digits for numeric data and the Date and Time format for dates, adjusted for the user's locale.

Data links use the format that is configured for the layer that the data link belongs to—you cannot configure formatting for individual fields in data links.

Format Date/Time Fields

Essentials allows you to configure how date/time data is formatted in the site's viewers. This allows end users to see and enter date/time values in the notation of the user's locale. You can choose date/time formats from a list of predefined formats or you can define custom formats.

Predefined Date/Time Formats

The predefined date/time formats that Essentials supports are based on the .NET Framework Standard Date and Time Format Strings. These formats use the notation and language of the user's locale. For example, dates are written in month, day, year order in the en-US locale and day, month, year order in nl-NL. Words are written in English in en-US and in Dutch in nl‑NL.

The following table lists the predefined date/time formats and gives examples of how the different predefined formats display in three sample locales.

Examples of Predefined Date/Time Formats for 2015-03-11 22:37:15 in Different Locales

Custom Date/Time Formats

Essentials supports the .NET Framework Custom Date and Time Format Strings, with the following exceptions:

• Forward slashes "/" and colons ":" are treated as literal characters.

• The "y" format specifier is treated the same as "yy", and "yyy" is treated the same as "yyyy". This means that years are displayed using two digits or four digits.

• The "z" and "zz" format specifiers are treated the same as "zzz". This means that time-zone offsets from UTC are measured in hours and minutes. The format specifiers take the configured Display Time Zone setting into account.

• The "t" format specifier is treated the same as "tt". This means that times in the 12-hour clock use the full "AM" or "PM" designator.

• The "F" format specifier is treated the same as "f", "FF" is treated the same as "ff", and so on. This means that the viewer always displays trailing zeros in the fractions of a second.

• Viewers display a maximum of 3 digits in fractions of a second. This means that time can be represented to millisecond precision. Longer format specifiers, like "fffff", are truncated to 3 digits.

• The "g" and "gg" format specifiers are not supported. These specifiers represent the era, such as A.D. If you use these specifiers, they will be ignored.

• The "K" format specifier is not supported. This specifier represents the time zone. If you use this specifier, it will be ignored.

For information about custom date and time format strings, refer to the .NET Framework documentation for Custom Date and Time Format Strings.

In custom date/time formats, the order of the format specifiers determines the order to display the day, month, and year—the order is not automatically localized. If your application may be viewed by users in locales that use a different order, make sure the format is unambiguous. You might want to use a format specifier that displays the name of the month, such as "MMM" or "MMMM".

Configure Date/Time Formatting

To save yourself from doing more configuration than necessary, configure date/time formatting by starting at the map service level and working down. First configure the map service to use the format that you want most of the date/time fields to use. Next, override the map service setting by configuring the layers that use a different format than the map service. Finally, override the layer setting by configuring the fields that use a different format than their layers.

To configure date/time formatting:

1. Follow the instructions that apply to you:

   Configure the Map Service-Level Date/Time Format

   1. In Manager, edit the map service that you want to configure, and then click the Display Settings tab.

      The formatting settings are in the Field Formatting area.

   Configure the Layer-Level Date/Time Format

   1. In Manager, click Map in the side panel, click the Map Services tab, expand the map service that the layer belongs to, and then click the Edit icon next to the layer.

   2. Click the Fields tab.

      The layer-level formatting settings are in the Default Formatting area.

   Configure the Field-Level Date/Time Format

   1. In Manager, click Map in the side panel, click the Map Services tab, expand the map service that the layer belongs to, and then click the Edit icon next to the layer.

   2. Click the Fields tab.

   3. If you have not yet added the field, add the field.

      This allows you to configure the field separately from the other fields in the layer.

      1. Click Add/Remove Fields.

      2. To add one or more fields, select the fields in the Excluded Fields column, and then click the Include button that is between the two columns.

         To select multiple fields, hold the Ctrl key down while you select the fields.

      3. To remove fields that have been added, select the fields in the Included Fields column, and then click the Exclude button that is between the two columns.

         You can also exclude fields after you close the Add/Remove Fields dialog box by clicking the Remove icon beside the field that you want to exclude.

      4. Click OK.

         The Fields tab lists the fields that you have added. The <all other fields> item is at the top of the list. The <all other fields> item enables you to change the settings for the fields that you have not added.

      5. Click Submit Field Changes.

         You can now individually re-order and change the settings of any added field, and batch change the settings of the excluded fields.

   4. Click the Edit icon next to the field.

2. In the Date Format box, select the format from the drop-down list.

3. If you selected Custom Date Format in the Date Format box, enter the custom format string that you want to use.

   Do not put quotation marks around the custom format string.

4. Apply your changes.

Format Number Fields

Essentials allows you to configure how numeric data is formatted in the site's viewers. This allows end users to see and enter numeric values in the notation of the user's locale. You can choose number formats from a list of predefined formats or you can define custom formats.

You do not need to configure formatting to fields with Esri's OID data type, such as ObjectID fields, Number formatting does not apply to OID fields, even though they have a numeric data type in Essentials.

Predefined Number Formats

The predefined number formats that Essentials supports are based on the .NET Framework Standard Numeric Format Strings. These formats use the notation and language for the user's locale. For example, the decimal mark is a period in the en-US locale and a comma in nl-NL. Words are written in English in en-US and Dutch in nl-NL.

The predefined number formats allow you to specify the number of decimal digits to show in the viewer. If a stored value has more decimal digits than the format displays, then the value is rounded—0.5 and greater is rounded up, and less than 0.5 is rounded down. For example, 0.2576 displays as 0.26 when the Decimal Places setting is set to 2. If a stored value has fewer decimal digits than the format displays, then the displayed value is padded with zeros. Setting the number of decimal places to 0 (zero) displays integers.

You do not have to configure the number of decimal digits to display. If you leave the Decimal Places setting blank for the Number, Fixed-point, or Percentage format, the viewer displays as many decimal digits as the stored value contains, to a maximum of four. For the Currency and Accounting formats, the viewer displays the conventional number of decimal digits for the specified currency, for example, two decimal digits for US dollars and euros, or zero decimal digits for Japanese yen.

The following table lists the predefined number formats and gives examples of how the different predefined formats display in three sample locales.

Examples of Predefined Number Formats in Different Locales

* The Unformatted Value column uses periods "." to represent the decimal mark.

Essentials recognizes numbers in both locale-specific formats (1,234,567·89) and invariant format used by en locales (1234567.89). In locales where the invariant format and locale-specific format conflict, it recognizes only the locale's interpretation. For example, the de locale uses periods as group separators (100.000), so the invariant format (100000) cannot be interpreted reliably.

Custom Number Formats

Essentials supports the .NET Framework Custom Numeric Format Strings, with the following exceptions:

• Essentials does not support the per mille placeholder.

• Essentials does not support exponential notation.

• Essentials does not support literal characters that appear in the middle of a number, for example, 000-0000.

For information about custom numeric format strings, refer to the .NET Framework documentation.

Configure Number Formatting

To save yourself from doing more configuration than necessary, configure number formatting starting at the map service level and working down. First configure the map service to use the format that you want most of the number fields to use. Next, override the map service setting by configuring the layers that use a different format than the map service. Finally, override the layer setting by configuring the fields that use a different format than their layers.

To configure number formatting:

1. Follow the instructions that apply to you:

   Configure the Map Service-Level Number Format

   1. In Manager, edit the map service that you want to configure, and then click the Display Settings tab.

      The formatting settings are in the Field Formatting area.

   Configure the Layer-Level Number Format

   1. In Manager, click Map in the side panel, click the Map Services tab, expand the map service that the layer belongs to, and then click the Edit icon next to the layer.

   2. Click the Fields tab.

      The layer-level formatting settings are in the Default Formatting area.

   Configure the Field-Level Number Format

   1. In Manager, click Map in the side panel, click the Map Services tab, expand the map service that the layer belongs to, and then click the Edit icon next to the layer.

   2. Click the Fields tab.

   3. If you have not yet added the field, add the field.

      This allows you to configure the field separately from the other fields in the layer.

      1. Click Add/Remove Fields.

      2. To add one or more fields, select the fields in the Excluded Fields column, and then click the Include button that is between the two columns.

         To select multiple fields, hold the Ctrl key down while you select the fields.

      3. To remove fields that have been added, select the fields in the Included Fields column, and then click the Exclude button that is between the two columns.

         You can also exclude fields after you close the Add/Remove Fields dialog box by clicking the Remove icon beside the field that you want to exclude.

      4. Click OK.

         The Fields tab lists the fields that you have added. The <all other fields> item is at the top of the list. The <all other fields> item enables you to change the settings for the fields that you have not added.

      5. Click Submit Field Changes.

         You can now individually re-order and change the settings of any added field, and batch change the settings of the excluded fields.

   4. Click the Edit icon next to the field.

2. In the Number Format box, select the format from the drop-down list.

3. Currency: If you selected the Currency or Accounting number format, enter the currency type of the stored data.

   For example, if the stored data is in euros, enter EUR. The default is USD (US Dollars).

   To see a complete list of currency codes, delete the default currency type—a drop-down list of currency codes will open. To find out what the codes stand for, refer to this list of ISO 4217 currency codes.

4. Decimal Places: If you selected one of the predefined formats, enter the number of decimal digits that you want to display.

   Alternatively, leave the Decimal Places setting blank to display up to four decimal digits (Number, Fixed-point, and Percentage formats) or the conventional number of decimal digits for the specified currency (Currency and Accounting formats). To display integers, enter 0.

   This precision setting cannot exceed the maximum representable IEEE 754 floating point. This is specified in the IEEE 754 standard. See double-precision floating-point format and significant figures for more information.

5. Custom Number Format: If you selected Custom Number Format in the Number Format box, enter the custom format string that you want to use.

   Do not put quotation marks around the custom format string.

6. Apply your changes.