An image question with the draw or annotate appearance allows users to draw a sketch on a blank canvas or annotate an image or snapshot of a map. The ArcGIS Survey123 field app includes a default drawing tools palette of eight tools, including arrows, generic marker symbols, and text labels. For more information regarding the default palette, see Draw mode.
In addition to the default drawing tools, you can create custom palettes for configuring drawing and annotation tools. For example, a utilities organization might have specific symbols and line styles that relate to electrical or gas works.
Note:
Custom palettes are not supported in the ArcGIS Survey123 web app.
To create a custom palette, complete the following:
- Configure the Python environment in ArcGIS Survey123 Connect so that you can run the New XLSPalette template and Convert XLSPalette tools.
- Prepare a custom palette using the XLSPalette specification.
- Ensure the XLSPalette template and any associated files are in the survey's media folder.
- Convert the XLSPalette template to a .palette file by running the Convert XLSPalette tool on the Media tab in Survey123 Connect.
- In the XLSForm for the survey, set the body::esri:style column for an image question with draw or annotate appearance to use a custom palette instead of the default palette by specifying palette=<palette_name>.
A custom palette is first configured in an XLSPalette template. The XLSPalette template must then be converted to a .palette file so that it can be added to the survey. XLSPalette templates are converted with a tool on the Media tab in Survey123 Connect.
Prepare a custom palette
A custom palette is configured in XLSPalette, an .xlsx file that contains the worksheets that will be converted to a .palette file that can be used in the survey.
To get started with custom palette design, you need an XLSPalette template. Survey123 Connect includes a New XLSPalette template tool to create a blank template. To run the tool, you must configure a Python environment in Survey123 Connect. For more information, see Configure Python.
Open the survey in Survey123 Connect. To create an XLSPalette template, click Tools and then click New XLSPalette template. A template file is created in the media folder named myXLSPalette1.xlsx. Alternatively, you can download a copy of the Survey123 XLSPalette template from ArcGIS Online.
Each worksheet in the XLSPalette template is a toolset: a group of tools in the custom palette. The rows on each toolset worksheet define the annotation tools in the toolset. The following example shows an XLSPalette configuration for three annotation tools for a gas pipeline inspection, containing two line tools and a marker tool:
| type | label | tool | symbol | textSymbol |
|---|---|---|---|---|
line | Gas Line (New) | line | color=Blue&size=5&style=dash | color=MediumBlue&size=14&anchor=bottom&italic |
line | Gas Line (Existing) | line | color=Yellow&size=5&outline.color=Black&outline.size=1 | color=#FFFFE0&size=14&anchor=bottom |
marker | Meter (New) | meter.svg |
For more information about the syntax and parameters you can use to design a custom palette, see XLSPalette specification. The full syntax is also described on the Reference worksheet in the XLSPalette template.
Ensure the XLSPalette template and any image files the palette uses, such as SVG marker symbols or toolset icons, are in the survey's media folder. The XLSPalette template must now be converted to a .palette file so it can be added to the survey.
Convert palette
To run the Convert XLSPalette tool, you must configure a Python environment in Survey123 Connect. For more information, see Configure Python.
Open the survey in Survey123 Connect and browse to the Media tab. The Media tab lists the contents of the survey's media folder. A convert button is next to .xlsx files. Click the convert button to run the Convert XLSPalette tool to convert the XLSPalette template to a .palette file that can be used in the survey.
When the conversion completes, the .palette file is saved to the media folder and appears on the Media tab.
Tip:
The name of the .palette file is the same as the source .xlsx file. As this name will be used as an XLSForm parameter, ensure that there are no spaces in the file name.
Add a palette to the survey
After creating and converting a custom palette, you can add it to the XLSForm. You can add as many custom palettes to the survey as you like; however, only one palette can be used in each draw or annotate question.
For an image question with the draw or annotate appearance, type palette=<palette_name> into the body::esri:style column, where <palette_name> is the name of the palette file without the .palette extension, for example: palette=Electrical.
The custom palette will be now be used for the image question, instead of the default palette.
To update a custom palette, make the necessary changes to the .xlsx file and run the Convert XLSPalette tool again from the Media tab. This replaces the .palette file in the media folder, and the changes are visible in Survey123 Connect once the form preview is updated. Republish the survey to see the changes in the Survey123 field app.
XLSPalette specification
The XLSPalette specification is designed specifically for creating drawing and annotation tools in Survey123. Custom palettes are configured in an .xlsx file using the XLSPalette syntax. The XLSPalette template consists of the following:
- One or more toolset worksheets, containing type, tool, symbol, and textSymbol columns. A toolset is a group of tools in a palette. A palette can contain as many toolsets as necessary. The name of each toolset worksheet will be visible in the Survey123 field app as the name of each toolset tab in a custom palette.
- A Reference worksheet that provides a guide to the syntax and parameters you can use to design a palette.
- A Version worksheet that provides information about when the XLSPalette template was last updated.
- A Lists worksheet that contains lookup tables for the data validation on the toolsets worksheets. Do not modify the content on this worksheet.
You can add or remove toolset worksheets as required. To add a new toolset worksheet, make a copy of an existing toolset worksheet to ensure that the formatting and data validation is preserved. Toolset worksheets that do not contain any rows other than the header row are ignored when the XLSPalette is converted to a .palette file.
When working with tool properties, consider the following:
- Most symbol properties are specified as name=value pairs and separated by an ampersand.
- Colors can be specified by standard HTML color names or hex color codes. You can use eight-character hex color codes to set opacity.
- Width and size units are in pixels.
- Line symbols support custom dash patterns.
- If the type of tool is text, an entry in the textSymbol column is required. For all other types, a textSymbol value is optional.
Types and tools
A palette can contain any combination of tool types. The supported types are line, area, marker, and text, and they must be provided in the type column on each toolset worksheet.
The line, area, and text types support various tools that determine the drawing style for that type. You can specify the tool in the tool column on each toolset worksheet. You do not need to specify a tool for the marker and text types.
For a full list of supported tools, see the Reference worksheet in the XLSPalette template.
Symbology
Each tool supports various symbol properties that can be specified in the symbol column on each toolset worksheet.
For lines, you can specify a custom dash pattern using one or more solid-space pairs in the format [n,n...], where n is the relative segment length, for example, [4,3,2,3].
For marker symbols, the first value can be the name of an Esri simple marker symbol or an image file name with a file extension. Supported image formats are SVG, PNG, and JPG. The simple marker symbols are circle, cross, diamond, square, triangle, and x.
For a full list of supported symbols and properties, see the Reference worksheet in the XLSPalette template.
Text
Each tool can have a text label attached to it. You can also specify a label on its own using the text type. The formatting for text is specified in the textSymbol column on each toolset worksheet.
For the alignment property, you can specify multiple alignment values separated by a comma, for example, alignment=left,middle.
The anchor property applies to line, area, and marker types only, and it specifies where the text label will be positioned relative to the graphic element.
For a full list of supported styles and properties, see the Reference worksheet in the XLSPalette template.
Toolset icon
Toolset icons are shown with the toolset names in the palette. By default, if all tools in a toolset use the same tool, the icon is automatically set to match that tool. To specify an icon for a toolset, append &icon= to the worksheet name, followed by either the name of an icon from the library of Esri Calcite UI icons or an image file saved in the media folder. Supported image formats are SVG, PNG, and JPG.
Tip:
For best results, use a single color on a transparent background for toolset icons. Toolset icons are rendered in grayscale in the palette.
Worksheet names are limited to 31 characters and can include spaces, for example, New Works&icon=electric.svg.