AttachmentElement | References | ArcGIS Maps SDK for JavaScript

import AttachmentElement from "@arcgis/core/form/elements/AttachmentElement.js";

const AttachmentElement = await $arcgis.import("@arcgis/core/form/elements/AttachmentElement.js");

Inheritance: AttachmentElement→Element→Accessor

Since: ArcGIS Maps SDK for JavaScript 5.1

An AttachmentElement defines how one or more attachments can participate in the Editor's form. Use this approach to set attachment configurations within a feature layer's formTemplate. When present in the form, the user has the ability to upload an attachment specific to its corresponding input.

Any existing applications making use of attachments outside of a FormTemplate will continue to work as they have in the past. However, to take advantage of the new capabilities provided by AttachmentElement, attachments must be configured in a FormTemplate and associated to either a feature layer or the Editor's layerInfo.
Support for attachment elements is limited to single feature updates.
Support is limited to form templates set on either the Editor's layerInfo or directly on a feature layer.
The feature layer must have attachments enabled and be editable for attachments.
For attachment elements that use AudioInput, ImageInput, or VideoInput, input methods that are configured as only allowing capture are not supported.
For attachment elements that use AudioInput, ImageInput, or VideoInput, minimum requirements apply only in mobile editing workflows when the input method is set to only allow capture and the minimum file count is greater than or equal to one.
If a form was authored using older workflows, the Editor automatically recognizes any existing attachments and applies a compatibility fallback to preserve existing behavior.
When a form supports attachment elements and no attachment elements are explicitly defined, existing feature attachments will not be displayed.
When using specific input types, such as AudioInput, ImageInput, VideoInput, or DocumentInput, existing attachments are displayed only if they match the element's keyword. Existing attachments without a matching keyword are not shown. To display attachments that do not have a corresponding keyword, use the general AttachmentInput instead. This input type provides a more general approach to displaying attachments and does not require a keyword to be specified by setting the attachmentAssociationType accordingly.

See also

FormTemplate

Example

// Create the attachment element
const attachmentElement = new AttachmentElement({
  label: "Tree images",
  input: { // autocastable to ImageInput
     type: "image",
     maxFileSize: 800,
  },
  attachmentKeyword: "treeKeyword"
  displayFilename: true,
  minAttachmentCount: 1,
  maxAttachmentCount: 5,
});


// Next pass in element to the FormTemplate
const formTemplate = new FormTemplate({
  title: "Tree inspection",
  description: "Attach tree info",
  elements: [attachmentElement] // Add element to the template
});

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	AttachmentElementProperties

See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
allowUserRename	boolean \| null \| undefined
attachmentKeyword	string \| null \| undefined
declaredClass readonly inherited	string	Accessor
description inherited	string \| null \| undefined	Element
displayFilename	boolean \| null \| undefined
editableExpression	string \| null \| undefined
filenameExpression	string
input	AttachmentInputUnion \| null \| undefined
label inherited	string \| null \| undefined	Element
maxAttachmentCount	number \| null \| undefined
minAttachmentCount	number \| null \| undefined
type readonly	"attachment"
useOriginalFilename	boolean \| null \| undefined
visibilityExpression inherited	string \| null \| undefined	Element

allowUserRename

Property

Type: boolean | null | undefined

Indicates whether renaming of attachments is allowed by the user. If true, the user can rename attachments when adding them to the form. If false, the user cannot rename attachments and the file name will be determined by the filenameExpression property or generated automatically if filenameExpression is not specified.

Default value: true

attachmentKeyword

Property

Type: string | null | undefined

A string to identify the attachment(s). When a file is attached using the form, this property is used to set the value of the keywords field for the attachment. When a form is displaying existing attachments, this property is used to query attachments using an exact match on the keywords field.

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

Since: ArcGIS Maps SDK for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

description

inherited Property

Type: string | null | undefined

Inherited from: Element

The element's description providing the purpose behind it.

displayFilename

Property

Type: boolean | null | undefined

Indicates whether to display the file name.

Default value: false

editableExpression

Property

Type: string | null | undefined

A reference to an Arcade expression that returns a boolean value. When this expression evaluates to true, the element is editable. When the expression evaluates to false the element is not editable.

See also

ExpressionInfo

filenameExpression

Property

Type: string

A string-based Arcade expression used to determine the file name of an attachment added through the form. If not specified, a unique name will be generated using the attachmentKeyword plus the current timestamp when attachment is added. This property is used when useOriginalFilename is set to false or when allowUserRename is set to false and the user adds an attachment without specifying a file name.

If wanting to set an attachment's filenameExpression, it should be handled in-line as part of the element rather than as a reference to a shared expression.

Default value: 'StandardizeFilename(`${$formElement.attachmentKeyword}_${Text(Now(), "YMMDDHHmmss")}`)'

Example

const attachmentElement = new AttachmentElement({
  label: "Tree canopy",
  allowUserRename: false,
  attachmentKeyword: "tree_canopy",
  displayFilename: true,
  // If not set, the default filenameExpression will generate a name using the
  // attachmentKeyword and current timestamp. For example: "tree_canopy_20240610123045"
  filenameExpression: 'StandardizeFilename(`${$formElement.attachmentKeyword}`)',
  input: { // autocastable to ImageInput
    type: "image",
    maxFileSize: 800
  },
  useOriginalFilename: false
});

input

autocast Property

Type: AttachmentInputUnion | null | undefined

The user-facing inputs used for the attachment element. This defines the type of attachments allowed.

label

inherited Property

Type: string | null | undefined

Inherited from: Element

A string value containing the field alias. This should not be used for referencing fields in Arcade expressions. Rather, the service FieldElement.fieldName should be referenced.

maxAttachmentCount

Property

Type: number | null | undefined

Defines the maximum number of attachments allowed for this element. If not specified, there is no maximum number requirement.

minAttachmentCount

Property

Type: number | null | undefined

Defines the minimum number of attachments required for this element. If not specified, there is no minimum number required.

For media attachment elements configured with AudioInput, ImageInput, or VideoInput, minimum file count validation is enforced only on mobile devices when the input is restricted to newly captured or recorded media and the minimum file count is greater than or equal to one.

type

readonly Property

Type: "attachment"

The type of the Element.

useOriginalFilename

Property

Type: boolean | null | undefined

Determines whether the uploaded attachment's file name is preserved. If false, the name is updated based on filenameExpression.

Default value: true

visibilityExpression

inherited Property

Type: string | null | undefined

Inherited from: Element

A reference to the ExpressionInfo.name of an Arcade expression defined in the FormTemplate.expressionInfos of the FormTemplate.

When this expression evaluates to true, the element is displayed. When the expression evaluates to false the element is not displayed. If no expression is provided, the element is always displayed. Care must be taken when defining a visibility expression for a non-nullable field as to make certain the specified field has either 1) a default value, or 2) is made visible to the end user to enter a value before submitting the form.

The expression must follow the specification defined in the Form Calculation Profile.
This expression references field values within an individual feature or in other layers and must return either a date, number, or string value.
The referenced expression must be defined in the form template's FormTemplate.expressionInfos.
It cannot be set inline within the element object.
Field and Group elements must be visible if the field or one of the grouped fields is required.

See also

Example

// Expression created within ExpressionInfos and is referenced in element
const expression = new ExpressionInfo({
  name: "alwaysHidden",
  expression: "false"
});

// Reference an already-defined visibilityExpression set within the ExpressionInfos
const fieldElement = new FieldElement({
  type: "field",
  fieldName: "inspemail",
  label: "Email address",
  visibilityExpression: "alwaysHidden"
});

formTemplate.expressionInfos = [ expression ];
formTemplate.elements = [ fieldElement ];

Methods

Method	Signature	Class
fromJSON inherited static	fromJSON(json: any): any	JSONSupportMixin
clone	clone(): AttachmentElement
toJSON inherited	toJSON(): any	JSONSupportMixin

fromJSON

inheritedstatic Method

Signature: fromJSON (json: any): any

Inherited from: JSONSupportMixin

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameters

Parameter	Type	Description	Required
json	any	A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns: any
Returns a new instance of this class.

clone

Method

Signature: clone (): AttachmentElement

Creates a deep clone of the AttachmentElement class.

Returns: AttachmentElement
A deep clone of the AttachmentElement instance.

toJSON

inherited Method

Signature: toJSON (): any

Inherited from: JSONSupportMixin

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns: any
The ArcGIS portal JSON representation of an instance of this class.