Esri custom columns

The Esri custom columns for XLSForm provide additional functionality for Survey123 users.

Field type

Use the bind::esri:fieldType custom column to control the type and length of a field to be created in ArcGIS for your survey questions.

For many questions, you can determine the type automatically by the XLSForm conversion service. Questions of the select_one type are converted to a string field in ArcGIS by default. If you require your choice list to store values as integers, you must explicitly define the field type as an integer.

To control the field type, enter one of the following values in the bind::esri:fieldType column:

  • esriFieldTypeString
  • esriFieldTypeDate
  • esriFieldTypeInteger
  • esriFieldTypeSingle
  • esriFieldTypeDouble
  • esriFieldTypeSmallInteger
  • esriFieldTypePointZ
  • esriFieldTypeGUID

Note that bind::esri:fieldType only controls the field type created in the feature layer. To control the field type for a question during a survey, use the bind::type column. For example, entering the value int in the bind::type column for a calculate question treats the field as an integer, rather than its default field type of string. The values accepted by the bind::type column are as follows:

  • int
  • decimal
  • string
  • date
  • dateTime
  • time

The bind::esri:fieldType column also accepts the null value, which causes the question to be omitted from the feature layer created. While the question is still present in your survey and behaves normally, the answer is not submitted to the feature layer and is not present when reviewing responses. This is ideal for calculations, constraints, or other questions that need to be present for presentation purposes but are not needed in the results.

The following question types do not support a null field type:

  • select_one or other
  • select_multiple or other
  • image
  • hidden
Note:

Geopoint, geotrace, and geoshape questions support a null field type only if the survey includes at least one other geopoint, geotrace, or geoshape question that does not have a null field type, or if the geopoint, geotrace, or geoshape is in a repeat.

Field length

Use the bind::esri:fieldLength custom column to control the length of string (text) fields to be created in ArcGIS for your survey questions.

Note:

You cannot control integer and decimal questions this way. Databases don't specify a length of a numeric field; the range of valid values is governed by the numeric field type. For example, an integer field stores any integer value between -2,147,483,648 and 2,147,483,647.

Field aliases

By default, a survey field's alias inherits the same value as the field's label, referred to primarily when the survey is opened in ArcGIS. You can change this by entering a value in the bind::esri:fieldAlias column, which then becomes the field's new alias.

Because hidden and calculate questions do not display on a form, contents of the label field are not preserved. This means that when you view your survey records in the Survey123 website or ArcGIS, you see the question name displayed in the column header for these types of questions. To force the column header of hidden and calculate questions to show a label, use the bind::esri:fieldAlias column in your spreadsheet to specify a label.

Input mask

Input masks provide a set format for text questions by using characters and symbols. When you apply an input mask to a question, all responses must follow the specific pattern defined by the input mask.

To apply an input mask to your question, define the mask in the body::esri:inputMask custom column.

Tip:

Input masks can only be applied to the text question type. For integer or decimal question types, use the constraint column to limit answers.

The following table lists the characters and symbols that you can use in an input mask:

CharacterMeaning

A

ASCII alphabetic character required. Characters can be A through Z and a through z.

a

ASCII alphabetic character permitted but not required.

N

ASCII alphanumeric character required. Characters can be A through Z, a through z, and 0 through 9.

n

ASCII alphanumeric character permitted but not required.

X

Any nonblank character required.

x

Any nonblank character permitted but not required.

9

ASCII digit required. Digits can be 0 through 9.

0

ASCII digit permitted but not required. Digits can be 0 through 9.

D

ASCII digit required. Digits can be 1 through 9.

d

ASCII digit permitted but not required. Digits can be 1 through 9.

#

ASCII digit, or plus or minus signs, permitted but not required.

H

Hexadecimal character required. Characters can be A through F, a through f, and 0 through 9.

h

Hexadecimal character permitted but not required.

B

Binary character required. Characters can be 0 through 1.

b

Binary character permitted but not required.

>

All following alphabetic characters are uppercase.

<

All following alphabetic characters are lowercase.

!

Switch off case conversion.

\

Escape the special characters listed above to use them as separators.

The mask consists of a string of characters and separators, optionally followed by a semicolon to end the input mask and a character to be used for blanks. The blank characters are always removed from the text after editing. The following table lists example masks:

Example maskDescription

>A<xxxxxxxxxxxx

Text that starts with a capital letter followed by any lowercase characters.

AAA-AAA-AAA;_

Unique identifier that uses dashes as separators, with a semicolon at the end of the input mask followed by an underscore to represent each character that is to be completed.

B9.99;-

Represents a pH value. The number is constrained to start only with 0 or 1 and can only include two decimal places. A semicolon ends the input mask, followed by a dash used to represent each character that is to be completed.

999-99-9999

United States Social Security number.

(999) 999-9999

United States phone number.

900 kg

Weight in kilograms between 0 and 999.

99999

United States 5-digit ZIP Code.

AAA

IATA airport code.

Question visibility

You can hide a question from view with an expression using the body::esri:visible column. This column hides the question if the expression it contains does not evaluate as true, while still keeping the contents of the question itself. For example, the expression ${edit_location}='yes' causes the question to only display if the edit_location question has been set to the value yes.

This behaves similarly to the relevant column, with both columns hiding a question until the expression in the column evaluates as true. The primary difference is that body::esri:visible doesn't clear the value of a question hidden by the expression and still submits the hidden value to the feature layer. This makes body::esri:visible useful if the field's default content should be required, such as a default or calculation.

Note:

Image and audio questions do not support being hidden by the body::esri:visible column.

Geopoint symbology

A geopoint question can display a custom symbol for the point marker on the map using the symbol parameter in the body::esri:style column of your survey. The parameter must provide the file name of the custom symbol, which must be a .png file in the media subfolder of your survey. The column's contents should look like this:

symbol=imagefile.png

The symbol parameter can also accept optional parameters to configure the display of the symbol on the map. Separate these parameters from the file name with a question mark and from each other with an ampersand (&).

  • The x parameter determines the symbol's horizontal anchor point. It accepts a value between 0 (representing the left edge of the image) and 1 (representing the right edge). If not defined, the default value is 0.5.
  • The y parameter determines the symbol's vertical anchor point. It accepts a value between 0 (representing the top edge of the image) and 1 (representing the bottom edge). If not defined, the default value is 1.
  • The scale parameter determines the scale at which the image is displayed. Values below 1 scale the image down, while values above 1 scale the image up.
Symbol style for geopoint

The value provided can either be a constant or a reference to a question, for example, symbol=${symbol_question}. Inline expressions are not supported.

Point overlays on maps

Point locations from the first geopoint question within a repeat can be displayed on any map question in your survey by setting the body::esri:style column for a geopoint, geotrace, or geoshape question to overlay=repeat_name. All points captured for the first geopoint question within that repeat will be displayed on the map. Additional parameters can be optionally used to customize the overlay symbology.

The optional parameters supported by the overlay style are as follows, and can be separated by an ampersand, for example, overlay=repeat_name&preview=true.

ParameterDescriptionExample

view

Show overlay points on the map question. The default value is true.

view=false

preview

Show overlay points on the preview map. The default value is false.

preview=true

icon

The name of the point symbol to use for map pins. Available symbols can be found in the ArcGIS Developer documentation, under Point Symbols.

icon=esri_pin_two

iconColor

The color of the icon used for map pins. This parameter accepts either a standard color name or hex color code. The default value is black.

iconColor=Blue

iconOutlineColor

The color of the outline used for map pins. This parameter accepts either a standard color name or hex color code. The default value is white.

iconOutlineColor=#FF4500

iconSize

The size of the icon as it appears on the map. The default value is 30.

iconSize=40

label

Survey question name to use as a label.

label=question_name

labelColor

The color of the label for a point. This parameter accepts either a standard color name or hex color code. The default value is black.

labelColor=#FFD700

labelOutlineColor

The color of the outline of the label. This parameter accepts either a standard color name or hex color code. The default value is white.

labelOutlineColor=Black

fontSize

The font size of the label for a point. The default value is 13.

fontSize=16

Group and repeat colors

You can set the colors for groups, pages, and repeats independently of the overall survey style by adding the backgroundColor and borderColor parameters to the body::esri:style column. Colors can be specified by standard HTML color names or hex color codes. You can provide these as a constant or as a reference to a question. Multiple parameters are separated by a space, for example:

backgroundColor=LightCyan borderColor=#483D8B

Note:

The backgroundColor and borderColor parameters are not supported in the Survey123 web app.

Grid style groups do not support borderColor.

Question height

The body::esri:style column accepts a height parameter for map questions.

You can set the height for a question by supplying the height parameter with a number and, optionally, a unit. The default unit is lines, referring to the height of the current input text font. For example, height=5 causes any of these questions to display five lines tall.

You can alternatively set the unit to a percentage of the screen height, or by number of pixels, by adding them as a suffix to the value without a space. For example, the following values are all accepted:

  • height=5
  • height=5lines
  • height=25%
  • height=250pixels

Image questions support the previewHeight parameter, controlling the height of the image preview after the image is selected. This parameter supports all unit types supported by height, but be aware that preview image height is ultimately limited by the device's screen width and the image's aspect ratio. Use previewHeight=0 if you want your image preview to be of maximum size without unnecessary blank space.

Text questions using the multiline appearance support the similar defaultHeight parameter, controlling how tall the text box is before being extended by an answer within it. The defaultHeight parameter does not support alternate height measurements and can only be set by number of lines, for example, defaultHeight=5.

Note:

Controlling the height of questions is not supported in the Survey123 web app.

Image capture methods

You can limit an image question to a particular capture method by specifying method=camera or method=browse in the body::esri:style column of the XLSForm. You can also set the appearance to new-front or new-rear for an image question to be limited to only using the device's camera, using the front-facing or rear-facing camera respectively as a default. When the annotate appearance is used, you can also specify method=map.

Placeholder text

Placeholder text can be provided for questions that accept a typed input (including text, integer, and decimal questions, and select_one questions with autocomplete appearance) by setting the placeholderText parameter in the body::esri:style column. By using placeholderText=@[hint] or placeholderText=@[guidance_hint], the hint or guidance hint will be hidden and the hint text will instead be placed inside the question's input area. Placeholder text will appear in the input area when the question is empty.

Note:

Placeholder text is not supported in the Survey123 web app.