FormCollection¶

class arcgis.mapping.forms.FormCollection(parent)¶

Bases: object

Represents a collection of forms in a webmap or item. A form is the editable counterpart to a popup – it controls the appearance and behavior of your data collection experience in ArcGIS Field Maps and Map Viewer Beta. These forms can then be used in the ArcGIS Field Maps mobile app and other applications. A form is stored as “formInfo” in the layer JSON on the webmap. This class will create a FormInfo object for each layer or table in the webmap/item data and return it as a list. You can then modify the FormInfo object to add and edit your form.

Parameter	Description
parent	Required `WebMap` or `Item`. This is the object which contains the layer, either an item of type `Feature Layer Collection` or a `Web Map`, where the forms are located. This is needed to save your form changes to the backend.

# USAGE EXAMPLE 1: Get Form Collection from WebMap
wm = arcgis.mapping.WebMap(item)
wm.add_layer(manhole_inspection)

# get forms from webmap, get individual form from FormCollection, modify form
form_collection = wm.forms
form_info_2 = form_collection[0]
form_info = form_collection.get(title="Manhole Inspection")
form_info.clear()
form_info.add_field(field_name="inspector", label="Inspector", description="This is the inspector")
form_info.add_group(label="Group 1",initial_state="collapsed")
form_info.update()

# USAGE EXAMPLE 2: Create Form Collection

from arcgis.mapping.forms import FormCollection
wm = arcgis.mapping.WebMap(item)
form_collection = FormCollection(wm)
form_info_1 = form_collection.get(item_id="232323232323232323")
form_info_1.title = "New Form"

get(item_id=None, title=None, layer_id=None)¶

Returns the form for the first layer with a matching item_id, title, or layer_id in the webmap’s operational layers. Pass one of the three parameters into the method to return the form.

Parameter	Description
item_id	Optional `str`. Pass the item_id for the layer or table whose form you’d like to return.
title	Optional `str`. Pass the title for the layer or table whose form you’d like to return.
layer_id	Optional `str`. Pass the layer_id for the layer whose form you’d like to return

Returns: FormInfo or None

FormInfo¶

class arcgis.mapping.forms.FormInfo(layer_data, parent, subtype_gl_data=None, **kwargs)¶

Bases: object

Represents a form in ArcGIS Field Maps and other applications. This matches with the formInfo property in a webmap’s operational layer.

For more please see: https://developers.arcgis.com/web-map-specification/objects/formInfo/

Parameter	Description
layer_data	Required `PropertyMap` or `dict`. This is the operational layer which contains the formInfo dict. It can be retrieved from a webmap using arcgis.mapping.WebMap(item).layers[0]
parent	Required `WebMap` or `Item`. This is the object which contains the layer, either an item of type Feature Layer Collection or a webmap. This is needed to save your form changes to the backend.
subtype_gl_data	Optional `PropertyMap` or `dict`. This is the operational layer representing a subtype group layer which contains the layer containing the form. It can be retrieved from a webmap using arcgis.mapping.WebMap(item).layers[0]

# USAGE EXAMPLE 1: Modify FormInfo
    from arcgis.mapping.forms import FormFieldElement
    wm = arcgis.mapping.WebMap(item)
    wm.add_layer(manhole_inspection)
    form_collection = wm.forms
    form_info = form_collection.get_form(title="Manhole Inspection")

    # edit form properties
    form_info.title = "Manhole Inspection Form"
    form_info.description = "The editable experience in ArcGIS Field Maps for data collection"

    # get element, add element
    new_element = FormFieldElement(label="Inspector Name", field_name="inspectornm",
                                  editable=True)
    form_info.add(element=new_element)
    same_element = form_info.get(label="Inspector Name")

    # add group, add second group, add to group
    form_info.add_group(label="Inspector Group",description="This is a group for inspectors")
    new_group = FormGroupElement(label="Group 1", description="New Group")
    group = form_info.add(element=new_group)
    group.add_field(field_name="inspection_date", label="Inspection Date")

    # move element, delete element
    form_info.move(element=new_group, index=0)
    form_info.delete(element=new_group)

    # save form into backend
    form_info.update()

add(element=None, index=None)¶

Adds a single FormElement to the form. You can add to the form either by instantiating your own FormFieldElement or FormGroupElement and passing it into the element parameter here, or you can type in a valid field_name in the form’s layer and this function will attempt to add it to the form.

Parameter	Description
element	Optional `FormFieldElement` or `FormGroupElement`.
index	Optional `int`. The index where you’d like the element in the form. If not provided, this function will add the new element to the end of the form.

Returns: The element that was added - FormFieldElement or FormGroupElement

add_all_attributes()¶: Adds all fields which can be valid form elements (string, date, int, double, small) to the form.

add_field(field_name, label, description=None, visibility_expression=None, domain=None, editable=None, hint=None, input_type=None, required_expression=None, index=None, editable_expression=None, value_expression=None, **kwargs)¶

Adds a single field FormElement element to the end of the form.

For more please see: https://developers.arcgis.com/web-map-specification/objects/formFieldElement/

Parameter	Description
field_name	Required `str`. The field name the form element corresponds to (where the data will be collected)
label	Required `str`. The label of the form element
description	Optional `str`. The description of the form element
visibility_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the visibility of the form element during data collection
domain	Optional `dict`. The domain of the form element
editable	Optional `bool`. Whether or not the form element is editable
hint	Optional `str`. The hint for the user filling out the form element
input_type	Optional `str` or `dict`. The input type for the form element in ArcGIS Field Maps. Options include: “text-area”, “text-box”, “barcode-scanner”, “combo-box”, “radio-buttons”, “datetime-picker”
required_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the necessity of the form element during data collection
index	Optional `int`. The index where you’d like the element in the form. If not provided, this function will add the new element to the end of the form.
editable_expression	Optional `FormExpressionInfo`. The Arcade expression determining the editablity of the form element during data collection
value_expression	Optional `FormExpressionInfo`. The Arcade expression which calculates a value for the form element during data collection

Returns: The element that was added - FormGroupElement

add_group(label, description=None, visibility_expression=None, initial_state=None, index=None, **kwargs)¶

Adds a single GroupElement to the form

Parameter	Description
label	Required `str`. The label of the group
description	Optional `str`. The description of the group
visibility_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the visibility of the form element during data collection
initial_state	Optional `str`. The initial state of the group
index	Optional `int`. The index where you’d like the element in the form. If not provided, this function will add the new element to the end of the form.

Returns: The element that was added - FormGroupElement

clear()¶: Clears the form to an empty state. Deletes all form elements currently in the form.

delete(element=None, label=None)¶

Deletes element from the form. You can use either the element param with a form element you get using get() or you can pass the label of the form element you’d like to move into the label param.

Parameter	Description
element	Optional `FormFieldElement` or `FormGroupElement`
label	Optional `str`. An actual field name (not alias) corresponding to a field in the form’s feature layer

Returns: FormFieldElement or FormGroupElement or False

property description¶: Gets/sets the description of the form

property elements¶: Returns elements in the form to the user - a list of FormElement

exists()¶: Returns whether the form exists for that particular layer or not.

property expressions¶: Returns Arcade expressions used in the form to the user - a list of FormExpressionInfo

feature_layer()¶: The feature layer associated with the form

get(label=None)¶

Returns a matching FormElement given a label

Parameter	Description
label	Optional `str` The label of the form element you want to return from the list of form elements

Returns: FormFieldElement or FormGroupElement or None

move(element=None, label=None, destination=None, index=None)¶

Moves a form element in the form to a new location. You can use either the element param with a form element you get using get() or you can pass the label of the form element you’d like to move into the label param.

Returns: True

property title¶: Gets/sets the title of the form

to_dict()¶

update()¶: Saves the form to the backend. If the form was derived from an Item, calling this function is required to save the form into the item. If the form was derived from a WebMap, you can either call this function or update(). If form has been cleared, removes formInfo from webmap

FormElement¶

class arcgis.mapping.forms.FormElement(form=None, element_type=None, description=None, label=None, visibility_expression=None, **kwargs)¶

Bases: object

The superclass class for FormFieldElement and FormGroupElement. Contains properties common to the two types of field elements. Instantiate a FormFieldElement or FormGroupElement instead of this class.

property description¶: Gets/sets the description of the form element.

property element_type¶: Get/Set the element type of the form element.

property label¶: Gets/sets the label of the form element.

to_dict()¶

property visibility_expression¶: Gets/sets the visibility expression of the form element.

FormFieldElement¶

class arcgis.mapping.forms.FormFieldElement(form=None, description=None, label=None, visibility_expression=None, domain=None, editable=None, field_name=None, hint=None, input_type=None, required_expression=None, editable_expression=None, value_expression=None, **kwargs)¶

Bases: arcgis.mapping.forms.FormElement

Represents a single field (non-group) element in a form. This corresponds with a field in the feature layer where you are collecting data. This is a subclass of FormElement, so you can modify properties such as label, description, and visibility_expression on these objects as well.

For more please see: https://developers.arcgis.com/web-map-specification/objects/formFieldElement/

Parameter	Description
form	Optional `FormInfo`. The form which contains this field element.
description	Optional `str`. The description of the form element
label	Optional `str`. The label of the form element
visibility_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the visibility of the form element during data collection
domain	Optional `dict`. The domain of the form element
editable	Optional `bool`. Whether or not the form element is editable
field_name	Optional `str`. The field name the form element corresponds to (where the data will be collected)
hint	Optional `str`. The hint for the user filling out the form element
input_type	Optional `str` or `dict`. The input type for the form element in ArcGIS Field Maps. Options include: “text-area”, “text-box”, “barcode-scanner”, “combo-box”, “radio-buttons”, “datetime-picker”
required_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the necessity of the form element during data collection

# USAGE EXAMPLE 1: Edit properties on form element
from arcgis.mapping.forms import FormExpressionInfo
wm = arcgis.mapping.WebMap(item)
wm.add_layer(manhole_inspection)
form_collection = wm.forms
form_info = form_collection.get_form(title="Manhole Inspection")

# edit element properties
form_element = form_info.get(label="Inspector Name")
form_element.label = "Inspector Name(s)"
form_element.description = "The inspector(s) who completed this manhole inspection")

# set visibility expression
el = form_info.add_field(field_name="jake_only", label="jake_only")
expression_info = FormExpressionInfo(name="expr0",title="New Expression",expression="$feature.inspector == 'Jake'")
el.visibility_expression = expression_info

property description¶: Gets/sets the description of the form element.

property domain¶: Gets/sets the domain of the form element.

property editable¶: Gets/sets the editability of the form element.

property editable_expression¶: Gets/sets the editable expression of the form element. Takes an object of FormExpressionInfo .

property element_type¶: Get/Set the element type of the form element.

property field_name¶: Gets the field name for the form element.

property hint¶: Gets/sets the hint of the form element.

property input_type¶

Gets/sets the input type of the form element.

Parameter

Description

value

Required string or dictionary.

Values:

“text-area” | “text-box” | “barcode-scanner” | “combo-box” | “radio-buttons” | “datetime-picker”

Returns: dictionary that represents the input type

property label¶: Gets/sets the label of the form element.

property required_expression¶: Gets/sets the required expression of the form element. Takes an object of FormExpressionInfo .

to_dict()¶

property value_expression¶: Gets/sets the value expression of the form element. Takes an object of FormExpressionInfo .

property visibility_expression¶: Gets/sets the visibility expression of the form element.

FormGroupElement¶

class arcgis.mapping.forms.FormGroupElement(form=None, elements=None, initial_state=None, description=None, label=None, visibility_expression=None, **kwargs)¶

Bases: arcgis.mapping.forms.FormElement

Represents a single group element in a form. This is a subclass of FormElement, so you can modify properties such as label, description, and visibility_expression on these objects as well.

For more please see: https://developers.arcgis.com/web-map-specification/objects/formGroupElement/

Parameter	Description
form	Optional `FormInfo`. The form which contains this group element.
description	Optional `str`. The description of the group element
label	Optional `str`. The label of the group element
visibility_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the visibility of the form element during data collection
initial_state	Optional `dict`. Options are “collapsed” and “expanded”

# USAGE EXAMPLE 1: Edit properties on group, add to group
from arcgis.mapping.forms import FormExpressionInfo
wm = arcgis.mapping.WebMap(item)
wm.add_layer(manhole_inspection)
form_collection = wm.forms
form_info = form_collection.get_form(title="Manhole Inspection")

# edit group properties, access elements within group
group_element = form_info.get(label="Group 1")
grouped_form_element = group_element.get(label="Inspector Name")
grouped_form_element.label = "Inspector Name(s)
group_element.label = "Inspector Information"
group_element.initial_state = "collapsed"

# add group, add to group, delete from group, delete group
new_group = FormGroupElement(form_info, label="Group 2", initial_state="expanded")
group = form_info.add(element=new_group)
grouped_element = group.add_field(field_name="inspection_date", label="Inspection Date")
group.add_field(field_name="inspection_city", label="Inspection City")
grouped_element.label = "Inspection Date"
group.move(grouped_element, index=1)
group.delete(grouped_element)
form_info.delete(group)

add(element=None, index=None)¶

Adds a single form element to the group. You can add to the group either by instantiating a FormFieldElement and passing it into the element parameter here, or you can type in a valid field_name in the form’s layer and this function will attempt to add it to the form.

Parameter	Description
element	Optional `FormFieldElement`
index	Optional `int`. The index where you’d like the element in the group. If not provided, this function will add the new element to the end of the group.

Returns: The element that was added - FormFieldElement

add_field(field_name, label, description=None, visibility_expression=None, domain=None, editable=None, hint=None, input_type=None, required_expression=None, index=None, editable_expression=None, value_expression=None, **kwargs)¶

Adds a single field FormElement element to the end of the group.

For more please see: https://developers.arcgis.com/web-map-specification/objects/formFieldElement/

Parameter	Description
field_name	Required `str`. The field name the form element corresponds to (where the data will be collected)
label	Required `str`. The label of the form element
description	Optional `str`. The description of the form element
visibility_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the visibility of the form element during data collection
domain	Optional `dict`. The domain of the form element
editable	Optional `bool`. Whether or not the form element is editable
hint	Optional `str`. The hint for the user filling out the form element
input_type	Optional `str` or `dict`. The input type for the form element in ArcGIS Field Maps. Options include: “text-area”, “text-box”, “barcode-scanner”, “combo-box”, “radio-buttons”, “datetime-picker”
required_expression	Optional `FormExpressionInfo`. The conditional visibility Arcade expression determining the necessity of the form element during data collection
index	Optional `int`. The index where you’d like the element in the form. If not provided, this function will add the new element to the end of the form.
editable_expression	Optional `FormExpressionInfo`. The Arcade expression determining how much editable the form element is during data collection
value_expression	Optional `FormExpressionInfo`. The Arcade expression which calculates a value for the form element during data collection

delete(element=None, label=None)¶

Deletes form element from the group. You can use either the element param with a form element you get using FormInfo.get() or you can pass the label of the form element you’d like to move into the label param.

Parameter	Description
element	Optional `FormFieldElement`
label	Optional `str` An actual field name (not alias) corresponding to a field in the form’s feature layer

Returns: The deleted element - FormFieldElement or False

property description¶: Gets/sets the description of the form element.

property element_type¶: Get/Set the element type of the form element.

property elements¶: Returns elements in the group to the user - a list of FormElement.

get(label=None)¶

Returns a matching FormFieldElement in the group given a label

Parameter	Description
label	Optional `str` The label of the form element you want to return from the list of form elements

Returns: FormFieldElement or None

property initial_state¶

Gets/sets the initial state of the form element.

Parameter

Description

value

Required string.

Values:

“collapsed” | “expanded”

property label¶: Gets/sets the label of the form element.

move(element=None, label=None, destination=None, index=None)¶

Moves a form element in the group to a new location. You can use either the element param with a form element you get using FormGroupElement.get() <:attr:`arcgis.mapping.forms.FormGroupElement.get>` or you can pass the label of the form element you’d like to move into the label param.

Returns: The element that was moved - FormFieldElement

to_dict()¶

property visibility_expression¶: Gets/sets the visibility expression of the form element.

FormExpressionInfo¶

class arcgis.mapping.forms.FormExpressionInfo(expression=None, name=None, title=None, return_type='boolean', **kwargs)¶

Bases: object

This class corresponds to a single expressionInfo in the expressionInfos list within a form.

For more please see: https://developers.arcgis.com/web-map-specification/objects/formExpressionInfo/

Parameter	Description
expression	Optional `str` This is an Arcade expression which you want to evaluate in ArcGIS Field Maps on whether or not this form element shows.
name	Optional `str` The unique identifier for the expressionInfo
title	Optional `int`. The user friendly name for the expressionInfo
return_type	Optional `str`. The return type of the expression in expressionInfo

property expression¶: Gets/sets the expression for the expression info.

property name¶: Gets/sets the name for the expression info.

property return_type¶: Gets/sets the return type for the expression info.

property title¶: Gets/sets the title for the expression info.

to_dict()¶