Seven handy tips for getting started creating a custom dictionary style
Dictionary styles provide a highly customizable way to visualize attribute-rich data in your maps and applications. With a look-up table of individual symbol parts, a dictionary script connecting attribute values to symbol keys, and a configuration file for fine tuning, these styles can be used together with the Dictionary Renderer to build complex symbols driven by multiple attributes in your data.
I created a dictionary style for the Alternative Fuel Stations layer in Living Atlas that provides information about each station at a quick glance.
In this blog, I will share some of my top tips for creating your own custom dictionary style while we take a closer look at the one I created. If you want to explore the style as you read, here are links to the style and a web map where a layer has already been configured with the style.
Tip 1 – Gather resources to use while building your style
Whenever I start building a new dictionary style, I am prepared with my favorite resources at hand. First is this blog by my colleague Thad: Create custom dictionary styles for ArcGIS. The blog shares all the tools and steps needed to build your style from start to finish. My go-to tools are:
- DB Browser for SQLite,
- Visual Studio Code,
- ArcGIS Pro, and
- A subset of the data to test the style along the way.
The Custom Dictionary Style Guide is another great place to get started with in-depth, step-by-step instructions for creating your own custom style. I also like to have the dictionary renderer toolkit handy. The toolkit is full of resources for understanding, creating, and troubleshooting dictionary styles, as well as a few sample styles worth exploring.
Tip 2 – Don't forget about built-in default symbol keys
Each individual symbol part has a unique key defined in the look-up table. The best way to create and edit these symbol parts is in ArcGIS Pro. First add the style to your project Catalog then double-click the Alternative Fuel Stations style to open the table. Here you will find all the symbol parts in the style.
Let’s focus on the Fuel Type symbols first. There are 7 fuel type symbols and one default symbol (we will get to that one in a moment), each with their own unique key. With exception of the default key, these keys follow the format “fuel-” followed by the fuel type abbreviation found in the Fuel_Type field.
The dictionary script is an Arcade script that contains instructions on how to use attribute values to build symbol keys. The dictionary script uses $feature.Fuel_Type to produce the fuel type key. This is the first key listed, so when a feature is evaluated, the type key is the first one returned.
But what happens when Fuel_Type is empty or the full name, “Electric” is used instead of “ELEC”? In these hypothetical cases, the script would return “fuel-” and “fuel-Electric”, two keys that do not exist in the look-up table. This is where the default symbol comes in!
Dictionary renderers have built-in default symbol keys that are used when the first key returned in the script doesn’t exist in the look-up table. All you have to do is add a symbol with following key: “Invalid_P” for points, “Invalid_L” for lines, or “Invalid_A” for polygons.
Tip 3 – Vary symbol property values with primitive overrides
In this style, the outline of the symbol is used to communicate two different pieces of information about the fuel station. If the outline is a solid line, the information has been verified, but if it is a dashed line, the information has not been verified. The color of the outline stroke indicates the operating status of the station: available, planned, temporarily unavailable, or unknown. There are 8 combinations of possible outlines:
Instead of requiring individual symbol parts for every combination, the style uses primitive overrides to drive the color of just two symbol parts: the solid verified outline and the dashed unverified outline.
A primitive override is a way to change a symbol property value, such as the outline color, differently per feature. Parts of a symbol can be tagged with a primitive name, which is used by the script to apply overrides to the parts that have been tagged with the specified name.
In the dictionary script, the status of the station specifies the color used in the override, poColor. The syntax for a primitive override is po:<primitive_name>|<property_name>|<value>. For this style this means that when drawing the verification symbol, for any part of the symbol tagged with status-color, the Color is replaced with the value of poColor:
Now to tag the symbol parts with the primitive name. This override will be applied to stroke of the verified and unverified symbols in the look-up table. From the look-up table, select the Verified symbol and navigate to the Layer Properties tab. From here use the element drop down to drill down to the Shape Fill symbol, then format that symbol to get down to the fill and stroke properties. In the structure tab, click the little tag symbol next to the stroke and specify status-color as the primitive name. Now repeat for the unverified symbol.
With the symbol elements tagged, the style now supports all 8 possible outline combinations of verification statuses and operating statuses using just two individual symbol parts.
Tip 4 – Take advantage of configuration properties
Now if you are familiar with the Alternative Fuel Stations Living Atlas layer you may be thinking, “wait a minute- there is no ‘verified’ field in that data!” You caught me. I am using a subset that I modified, adding the ‘verified’ field which will come in handy for a future blog. This style works with the verified field, but maybe you are using the Living Atlas layer and don’t have that field in your data. That's why I created a configuration property that allows you to include or ignore the verification field.
The configuration file is a JSON object where you can define additional configuration options that alter how symbols draw. This style has multiple configuration options, but we’ll start with the use_Verified_Field configuration. Here I specified the name of the configuration, the default value, possible values, and a brief description. I also included the Verified field as a symbol field leveraged by the dictionary script. You can really see this come to life in ArcGIS Pro:
When the use_Verified_Field configuration is on, the dictionary script will use the value in the verified field to return a key for a solid or dashed line. When it is off, the dictionary script will return a key for the solid line for all features. To leverage the value of a configuration property in the dictionary script, use the syntax $config.name or in this case, $config.use_Verified_Field:
Now anyone using this style to symbolize a layer can control if the verified field is used.
Tip 5 – Know when to use a symbol field or text field for labels
That last configuration property was about how symbol parts are calculated using a symbology field in the data, but now let’s look at a property to turn labels on and off. In the layer, EV charging stations include information about the network they belong to in the EV_Network field. If a station doesn’t belong to a network, that field is populated with “Non-networked.”
First, add a new symbol for the label to the look-up table then make sure it is a shape text symbol in the layer properties tab. To use the EV network in the data, replace the text string with the field name in brackets, in this case, [EV_Network]:
In the configuration file, I created the show_EV_Network property so that you can turn the labels on and off. I also specified the EV_Network field as a symbol field. Why not a text field you ask? Text fields work great when you want to label all features. If I had chosen to use a text field, every feature would be labeled with their EV_Network value and EV stations that aren’t networked would have a “Non-networked” label. I decided I only wanted networked EV stations to be labeled, so made that a condition in the dictionary script:
Text fields cannot be accessed by the dictionary script, which means that they can’t be used as variables in the logic. Since the script needs to use the EV_Network value to determine whether to return the label key, I included the EV_Network field as a symbol field in configuration file.
Tip 6 – Use unique primitive names
The final configuration property in this style is the show_Connector_Type property which allows you to show or hide a banner that displays all the available connector types at an EV charging station. The available connectors are listed in a single field in the Alternative Fuel Stations layer. While the configuration is a simple on/off property like the others, this portion of the dictionary script is a bit more complicated as we have to consider which connector symbols are used, how those symbols are positioned, and how wide the banner needs to be to accommodate that many symbols:
Let’s begin with the banner width. The look-up table contains symbol parts for banners that will fit 1, 2, 3, or 4 connector symbols. In the dictionary script, we create an array of the available connector types and count the number of objects in the array to determine which banner to use.
Then the connector symbol keys are returned. The script uses a for loop to iterate through each object in the array, returning the key for each corresponding connector type symbol part. If we stopped here, all the connector symbols would draw on top of each other. Luckily, we can use primitive overrides here!
The X offset override shifts tagged symbol parts along the x axis. With each iteration of the for loop, 11 points are added to the X offset, so that the following symbol will be 11 points to the right of the previous symbol. In the look-up table, each connector symbol has been tagged with a primitive name that follows the syntax [connector type]_marker (e.g. J1772_marker, CHAdeMO_marker, etc.).
So if a station has two connectors, J1772 and CHAdeMO, the keys would look like this:
- Banner key: background-2
- Connector type keys: con-J1772;po:J1772_marker|OffsetX|17;` and `con-CHAdeMO;po:CHAdeMO_marker|OffsetX|28;
Unlike our previous example with primitive overrides, each symbol part needs to have a unique primitive name because the offset values to be applied to each symbol so that they do not overlap.
Tip 7 – Return keys in drawing order
In the last line of this dictionary script, we return the string of keys, which tells the client what individual symbol parts to use to create the final symbol. The order the keys appear in the string dictates the order in which symbol parts are drawn. When you look at a final symbol drawn with this style, you can see that the connector types draw on top of the banner, and the banner draws under the fuel type symbol and the outline, while accessibility indicator draws on top:
In this dictionary when all the configuration properties are on, the keys are returned in the following order: fuel type, network name, EV banner, EV connector types, verified key, fuel type, and access. The fuel type key is returned twice because the built-in default key (Invalid_P) is used only when the first key returned produces a key not in the look-up table. Adding the fuel type key a second time ensures proper drawing order, but another option is adjusting the symbol parts to remove unnecessary fill symbols that may “bury” symbols.
And that’s it- you now have all my top tips for creating your own custom dictionary style! You can dig into this style further by downloading it here or get started building your own custom style. Let me know in the comments below what ideas you have for creating custom dictionary styles!