4.0.0 dictionary spec updates

README.md

@@ -3,6 +3,7 @@ Extend ArcGIS Pro, the ArcGIS API for JavaScript, and the ArcGIS Runtime SDKs by
 
 * [Understanding the dictionary](/docs/understanding-the-dictionary.md)
 * [Tips for creating custom dictionaries](/docs/tips-for-creating-custom-dictionaries.md)
+* [Working with different field types](/docs/working-with-different-field-types.md)
 * [Troubleshooting drawing issues](/docs/troubleshooting_drawing_issues.md)
 * [Add a new identity to MIL-STD-2525C](/docs/add-a-new-identity-to-MIL-STD-2525C.md)
 * [Add a new symbol set to MIL-STD-2525D](/docs/add-a-new-symbol-set-to-MIL-STD-2525D.md)
@@ -20,7 +21,21 @@ The dictionaries can be shared as web styles for use with ArcGIS Runtime SDKs 10
 
 _Note: The ArcGIS API for JavaScript version 4.16 and higher support point, line, and polygon symbols. The ArcGIS API for JavaScript versions 4.13 through 4.15 support point symbols only._
 
-A previous version of this toolkit allowed for creation of dictionary styles that worked with ArcGIS Pro 2.4 and ArcGIS Runtime SDKs 100.6. It is archived as a [branch](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/2.0.0) of this repository and it's recommended that dictionaries be upgraded to version 3.0.0, which this toolkit documents from that previous 2.0.0 version. See [Upgrading dictionary styles from a previous version](docs/upgrading-dictionary-styles-from-a-previous-version.md) for steps to upgrade.
+Previous versions of this toolkit allowed for the creation of older version dictionaries. These are archived as branches of this repository. The table below shows the branches available and the versions of the dictionary, ArcGIS Pro and ArcGIS Runtime SDK that they correspond to. It is recommended that dictionaries be upgraded to version 4.0.0, to achieve the full functionality of the dictionary. See [Upgrading dictionary styles from a previous version](docs/upgrading-dictionary-styles-from-a-previous-version.md) for steps to upgrade.
+
+
+
+| Branch | Notes | ArcGIS Pro | ArcGIS Runtime SDK | ArcGIS Maps SDK for JavaScript | Dictionary Version |
+| -------| ----- | ---------- | ------------------ | ------------------------------ | ------------------ |
+|master |	Dictionary version 4.0.0 | Pro 3.2 or higher	| 200.2 or higher	| 4.27 or higher | 4.0.0 |
+|[release/3.0.0](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/3.0.0) | Add-ins are for ArcGIS Pro 3x, dictionary version 3.0.0	| Pro 3.0 or higher	| 100.7 or higher | 4.13 or higher |	3.0.0 |
+|[release/2.9.0](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/2.9.0) |	Add-ins are for ArcGIS Pro 2x |	Pro 2.5 - Pro 2.9 |	100.7 or higher	| 4.13 or higher | 3.0.0 |
+|[release/2.0.0](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/2.0.0) |	Dictionary version 2.0.0 |Pro 2.4 |	100.6	| NA | 2.0.0 |
+
+
+
+
+
 
 See the [ArcGIS Pro system requirements](https://pro.arcgis.com/en/pro-app/get-started/arcgis-pro-system-requirements.htm) for requirements to run ArcGIS Pro.
 

docs/README.md

@@ -1,5 +1,6 @@
 * [Understanding the dictionary](understanding-the-dictionary.md)
 * [Tips for creating custom dictionaries](tips-for-creating-custom-dictionaries.md)
+* [Working with different field types](working-with-different-field-types.md)
 * [Troubleshooting drawing issues](troubleshooting_drawing_issues.md)
 * [Add a new identity to MIL-STD-2525C](add-a-new-identity-to-MIL-STD-2525C.md)
 * [Add a new symbol set to MIL-STD-2525D](add-a-new-symbol-set-to-MIL-STD-2525D.md)

docs/tips-for-creating-custom-dictionaries.md

@@ -13,3 +13,5 @@
 * When using invalid symbols in the dictionary to symbolize features whose attributes do not produce an existing key in the style, it is necessary to hard code specific keys for the invalid symbols. For point symbols the key needs to be `Invalid_P`. For line symbols the key needs to be `Invalid_L`. For polygon symbols the key needs to be `Invalid_A`.
 
 * Names used for symbol attributes, text attributes and configuration fields should be unique.  The name should not be duplicated even if they are in different groups.
+
+* When using Arcade operators that require numeric, date or time data types ensure the dictionary version is 4.0.0.  See [Working with different field types](../docs/working-with-different-field-types.md) for examples.

docs/understanding-the-dictionary.md

@@ -40,7 +40,7 @@ This is the name that shows in the Dictionary symbology pane in ArcGIS Pro.
 
 **_dictionary_version_**
 
-This is the version of the dictionary. The minimum version number for a custom dictionary is `2.0.0`.  This documentation covers version 3.0.0. For documentation of version 2.0.0, see the archived [branch](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/2.0.0) of this repository. For details on how to upgrade a dictionary, see [Upgrading dictionary styles from a previous version
+This is the version of the dictionary. The minimum version number for a custom dictionary is `2.0.0`.  This documentation covers version 4.0.0. For information on versions and details on how to upgrade a dictionary, see [Upgrading dictionary styles from a previous version
 ](docs\upgrading-dictionary-styles-from-a-previous-version.md). Version `3.0.0` or higher is required to share the dictionary as a web style.
 
 **_arcade_version_**

docs/upgrading-dictionary-styles-from-a-previous-version.md

@@ -1,14 +1,42 @@
 # Upgrading dictionary styles from a previous version
 
 ## Versions
-This toolkit defines how to create a dictionary of version `3.0.0`. [A previous version of the toolkit](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/2.0.0), documented version `2.0.0` and we recommend upgrading dictionary styles to the `3.0.0` specification for full compatibility with the web styles and the ArcGIS API for JavaScript.
+We recommend dictionaries versions of `3.0.0` or `4.0.0` for full compatibility with the web styles and the ArcGIS Maps SDK for JavaScript.  Both dictionary versions are fully compatible with those specification.  Version `4.0.0` has additional functionality for supporting native data types without converting the values to strings.  See [Working with different field types](docs/working-with-different-field-types.md) for additional details.
 
-## Upgrading the style
+Version `2.0.0` dictionaries cannot be shared as web styles and are not compatible with the ArcGIS Maps SDK for JavaScript.  It is highly recommended to upgrade these dictionaries.
+
+
+| Dictionary Version  | Version Notes | ArcGIS Pro | ArcGIS Runtime SDK | ArcGIS Maps SDK for JavaScript | Branch |
+| ------------------ | ----- | ---------- | ------------------ | ------------- |------------------ |
+|4.0.0 |	Support for native data types | Pro 3.2 or higher	| 200.2 or higher	| 4.27 or higher | master |
+|3.0.0 | Usage of $feature and $config to be more Arcade compliant	| Pro 3.0 or higher	| 100.7 or higher | 4.13 or higher |	[release/3.0.0](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/3.0.0)|
+|2.0.0 |	Initial version |Pro 2.4 |	100.6	| NA | [release/2.0.0](https://github.com/Esri/dictionary-renderer-toolkit/tree/release/2.0.0)|
+
+## Upgrading 3.0.0 to 4.0.0
+Upgrading the dictionary to version `4.0.0` is optional but does offer more control over the functionality of the operators used in the script because the native data types are preserved.
+
+1. The first change is that the value of key `dictionary_version` in the `meta` table must be changed from `3.0.0` to `4.0.0`.
+
+2. Depending on the operators used in the script it may be necessary to make adjustments in the script.  Comparison operators, like == and !=, always consider different data types as not equal.  If these are used in the script they will need to be adjusted.  
+
+An example of this can be seen in the [Park Amenities](../dictionary_examples/Park_Amenities) dictionary.
+In the script, icons are shown for the different amenities by checking if the attribute value does not equal zero. The != operator is used for this comparison.  To upgrade to `4.0.0` it is necessary to remove the single quotes or the comparison will fail and symbols will unexpectedly draw.
+
+In `3.0.0` the script would be
+`if ($feature.TENNIS != '0')`    which is an explicit string comparison.
+
+In `4.0.0` the script would be
+  `if ($feature.TENNIS != 0)`    which is a number comparison. 
+
+If you are working with a custom dictionary that is based on the Joint Military Symbology or NATO Joint Military Symbology specifications the best way to identify changes that are needed in the script is to compare your custom script to the `4.0.0` versions of the dictionaries available from ArcGIS Online. The `4.0.0` script is more robust for different database schemes; however, the logic of the military specifications requires the symbol ID codes to be considered as string.  Modifications were made to ensure the database is properly converted to what the script requires.
+
+
+## Upgrading 2.0.0 to 3.0.0
 
 Upgrading the dictionary requires two steps and are typically done with manual edits of the SQLite database:
 
 1. The first change that must be made is that the Arcade script value stored in the style `meta` table key `dictionary_script` must be updated to reflect input parameters being passed in using `$feature` and `$config`. Previously, field values were passed in as `$fieldname` and a configuration values were passed in as `$configurationentryname`. In `3.0.0` dictionaries, all feature values are passed in via a `$feature` feature object and configuration values are passed in with a `$config` dictionary. So, the above example would be passed in now as `$feature.fieldname` and `$config.configurationentryname`. For the mil2525d dictionary, an example of this change would be `$sidc` changing to `$feature.sidc` and `$frame` changing to `$config.frame`.
 
 1. The final change is that the value of key `dictionary_version` in the `meta` table must be changed from `2.0.0` to `3.0.0`.
 
-Once the above steps are complete and your SQLite database is saved, your dictionary is upgraded.
+Once the above steps are complete and your SQLite database is saved, your dictionary is upgraded.

docs/working-with-different-field-types.md

@@ -0,0 +1,63 @@
+# Working with different field types
+
+Before version `4.0.0`, the values for all attribute fields used in the dictionary were converted to string values regardless of the field type.  In version `4.0.0` of the dictionary, Arcade will receive the native data type of the attribute field which will give more control over the functionality of the operators used in the script. Honoring the native data types ensures that numbers, dates, and times are not impacted by localization and formatting changes the way string values are.
+
+The `3.0.0` version of the dictionary is still supported. For dictionaries that consume string values or use Arcade operators that require strings there is no need to upgrade the dictionary. For steps for upgrading `3.0.0` dictionaries see [Upgrading dictionary styles from a previous version](docs/upgrading-dictionary-styles-from-a-previous-version.md).
+
+## Numeric field example
+
+The results for numeric data types may be different for some Arcade operators depending on if the values are received as the true numeric type or converted to string. For additional information see the [implicit casting rules](https://developers.arcgis.com/arcade/guide/type-casting/#implicit-casting) from Arcade.
+
+An example of this can be seen in the [Park Amenities](../dictionary_examples/Park_Amenities) dictionary with the configuration to show the count for the number of sport facilities.  
+
+In the script, there is a configuration option to show a count for the number of sport fields and courts available for the public at each park.  The count is derived by adding together the values in multiple numeric attribute fields.
+
+```
+
+// Show sport facility count
+if (_show_sportfacilitycount) {
+    var count = $feature.SOCCFOOT + $feature.BASKETBALL + $feature.BASEBALL + $feature.SOFTBALL + $feature.TENNIS;
+	keys += ';sport_count_label';
+	keys += ';po:sport_facility_count|TextString|';
+        keys += 'Sport facilities: ' + count;
+  
+```
+
+If numeric data values are converted to strings in the script and then used by the + operator, adding the values for the different sports facilities will result in the values being concatenated because the operator arguments are strings.
+
+![sport facility string](images/sportfacilitystring.PNG)
+
+
+However, when the numeric data type is maintained as a number the values are summed. See [arithmetic statements](https://developers.arcgis.com/arcade/guide/type-casting/#arithmetic-statements) for details about the + operator and other arithmetic operators.
+
+![sport facility numeric](images/sportfacilitynumeric.PNG)
+
+
+
+
+
+
+
+## Date field example
+
+With a 3.0.0 dictionary, ArcGISPro will format date/time as a string like this (as seen in the Attribute Table).
+
+10/13/2023 10:12:00 PM
+
+This format doesn't convert easily to a date/time value in Arcade. As a result, it can be difficult to incorporate date/time fields in the script for anything more than labels.
+
+A 4.0.0 dictionary will receive native date fields, which can be used with the [date functions](https://developers.arcgis.com/arcade/function-reference/date_functions/) Arcade operators directly.
+
+An example of this can be seen with the [Service Calls](../dictionary_examples/Service_Calls) dictionary where the DateDiff operator is used to flag calls with a long wait time between when a call is received and when the call is dispatched.
+
+The data has two date fields, one for when the call is received and one for when the call is dispatched. The differences between these two fields can be compared in the identified units. Calls that are dispatched more than 4 hours after they are received are flagged with an additional icon.
+
+```
+if (DateDiff($feature.DispatchTime, $feature.CallTime, 'hours')>4){
+	keys += ';WARNING';	
+```
+
+![service call date comp](images/servicecalldatecomp.png)
+
+If you need a string representation of the date/time, Arcade has more options to format the value to accommodate the rendering needs. See [text_functions](https://developers.arcgis.com/arcade/function-reference/text_functions/#text) for details.
+

docs/working-with-overrides.md

@@ -6,6 +6,11 @@ A primitive override is a way to change a symbol property value differently per
 
 The syntax for a primitive override is `po:<primitive_name>|<property_name>|<value>` which means: for this symbol, replace `<property_name>` by `<value>` for all parts that are tagged `<primitive_name>`.  The property name needs to match the CIM property name.  Names can be found in the [CIMSymbols specification](https://github.com/Esri/cim-spec/blob/master/docs/v2/CIMSymbols.md).  The first letter of the property will need to be capitalized.
 
+The primitive name will apply to all the symbols identified with the keys. Symbols that share the same primitive name will have the same override applied.  An example of this can be seen in the [color override example](https://devtopia.esri.com/ArcGISPro/dictionary-renderer-toolkit/blob/main/docs/working-with-overrides.md#example-of-color-overrides) below.  
+
+It is important to note that one primitive name equals one overridden value. Different override values cannot be applied to the same primitive name. To apply different values it is neccessary to have different primitive names. This is illustrated by the [offset override example](https://devtopia.esri.com/ArcGISPro/dictionary-renderer-toolkit/blob/main/docs/working-with-overrides.md#example-of-offset-overrides) below.
+
+
 ## Adding primitive names to symbols in the dictionary
 
 In order to apply an override to a symbol part, the part needs to have a primitive name assigned.  The primitive name can be set by editing the symbol in the catalog view in ArcGIS Pro.  Primitive names can only be set on dictionary styles.
@@ -90,11 +95,11 @@ When building the grid of symbols that represent the park amenities, the functio
 
 ```
 // Park amenities
-if ($feature.Parking == 'Yes') {
+if ($feature.PARKING == 'Yes') {
     keys += ';Parking';
     addOffsetOverrides('parking_marker');
 }
-if ($feature.Restroom == 'Yes') {
+if ($feature.RESTROOM == 'Yes') {
     keys += ';Restroom';
     addOffsetOverrides('restroom_marker');
 }
@@ -103,7 +108,7 @@ if ($feature.Restroom == 'Yes') {
 The resulting key string for offsetting the icons for Ross Park would be:
 `Parking;Playground;po:playground_marker|OffsetX|15;Picnic;po:picnic_marker|OffsetX|30;Barbeque;po:barbeque_marker|OffsetX|45;Baseball;po:baseball_marker|OffsetY|-15;Basketball;po:basketball_marker|OffsetX|15;po:basketball_marker|OffsetY|-15;Soccer;po:soccer_marker|OffsetX|30;po:soccer_marker|OffsetY|-15`
 
-The primitive names used for the offsets, such as playground_marker, are unique to a single symbol so the offset can be applied to the individual amenities to create the grid.
+The primitive names used for the offsets, such as playground_marker, are unique to a single symbol so the offset can be applied to the individual amenities to create the grid. You cannot have multiple offset values applied using the same primitive name.
 
 
 ## Example of color overrides
@@ -137,7 +142,7 @@ The resulting key string for coloring the icons with the frame off for Ross Park
 While the primitive names for the offsets are unique for each symbol allowing the offsets to be applied for the individual amenities, the primitive names for the frame and icon are the same for all the symbols.  This allows for the color to be globally overridden for all symbols.
 
 
-Another example of a color override is in the [Service Call](../dictionary_examples/Service_Calls) dictionary where the color of the symbol is driven by the value in an attribute field.  In this dictionary, services are symbolized base on the type of call and the status of the call.  The type of call dictates the icon in the center of the hexagon while status controls the color of the outline on the hexagon.
+Another example of a color override is in the [Service Calls](../dictionary_examples/Service_Calls) dictionary where the color of the symbol is driven by the value in an attribute field.  In this dictionary, services are symbolized base on the type of call and the status of the call.  The type of call dictates the icon in the center of the hexagon while status controls the color of the outline on the hexagon.
 
 *Service Calls*