: Create custom symbols with the ArcGIS API for JavaScript

ArcGIS API for JavaScript

The 4.18 release of the ArcGIS API for JavaScript introduced an app called the CIM Symbol Builder. This app allows you to visually design a CIM symbol and export the symbol to a JSON string for use in a web application built with the ArcGIS API for JavaScript.

CIMSymbols are multi-layer vector symbols for features and graphics used throughout the ArcGIS platform. They provide unlimited flexibility so that you can create very elaborate and intricate symbols. Previously, such symbols could only be achieved using pre-generated images rendered as PictureMarkerSymbols.

CIM symbols are rendered based on the definition stored in the data property. This property is a well-defined JSON string that complies with the CIM specification, which can be difficult to author from scratch. This app can be a handy tool for developers, allowing them to get immediate visual feedback when altering the CIM JSON. It also allows users to create CIM symbols by combining pre-existing symbols and modifying their attributes.

Add a symbol layer

Start by adding symbol layer(s) from the symbol gallery. Click the ADD SYMBOL LAYER button and choose a symbol layer from the pre-defined symbols in the Icons, Shapes, or Custom categories.

Or you can import your own symbol by adding symbol JSON in the custom tab of the symbol gallery.

You can also import a web style from the “+” tab.

Edit symbol layer properties

Edit the properties of the symbol layers until you have your desired symbol. There are three supported symbol layers in the CIM Symbol Builder – each will have different properties that can be modified.

CIMVectorMarker
CIMPictureMarker
Text

CIMVectorMarker

Most of the symbol layers in the pre-defined symbol gallery are CIMVectorMarker symbol layers. Click on the symbol layer name to access the properties to edit. You will be able to change properties like size, rotation, anchor point, and offset.

edit symbol layer properties — Click the symbol layer to edit its associated properties. In this image, we rotate the original symbol clockwise by 90 degrees.

You can expand the layers in the symbol editor to get to the embedded layers within the specified layer. From there, you will be able to access additional properties that you can customize, such as the color and opacity of the embedded CIMSolidFill or CIMSolidStroke.

CIMPictureMarker

CIMPictureMarker allows you to add a picture as a symbol layer in your symbol. We recommend using an image data URI for the URL property of a CIMPictureMarker to avoid any potential cross domain (CORS) issues. Keep in mind that the color of the image will not change if any color visual variables are applied to the symbol. You can add a CIMPictureMarker symbol from the “Custom” tab in the symbol library.

Text

A text layer can be considered as a special type of CIMVectorMarker layer – it is an embedded text symbol in a CIMMarkerGraphic of a CIMVectorMarker. To edit the properties of the text symbol, you must click the CIMMarkerGraphic to access its properties. You can add a text layer from the “Custom” tab in the symbol gallery.

View your symbol on the map

You can test your symbol on the map by clicking the APPLY TO FEATURE LAYER button. This will apply the symbol you created to the renderer of the feature layer.

Get the symbol JSON

Once you are satisfied with the way your symbol looks, you can copy out the symbol JSON to add it to your own app! Use the GET SYMBOL JSON button to see the symbol’s JSON. Then, click the COPY JSON button to quickly copy the JSON to your clipboard to use it in your app. The symbol JSON should be applied to the CIMSymbol.data.symbol property, like this:


// Modules required: 
// esri/symbols/CIMSymbol

var symbol = new CIMSymbol({
    data: {
        type: "CIMSymbolReference",
        symbol: {} // ENTER SYMBOL JSON HERE
    }
});

You can test the symbol JSON you created in this Codepen. Simply replace the value of cimSymbolJSON on line 43 with your symbol JSON.

Final notes

In most cases SimpleMarkerSymbol, PictureMarkerSymbol, or other familiar and easy-to-use symbols will satisfy your requirements. However, some of your apps may require elaborate symbols that cannot be rendered with these traditional symbols. That’s where CIM symbols come in. This article introduces a visual editor for CIM marker symbols that saves you the effort of learning the CIM spec and editing raw JSON. We can’t wait to see the awesome symbols that you create using the CIM Symbol Builder!