@vertigis/viewer-spec/messaging/registry/edit.d.ts

VertiGIS Viewer Specification

import type FieldElement from "@arcgis/core/form/elements/FieldElement.js";
import type { Attachment } from "@vertigis/arcgis-extensions/data/Attachment";
import type { Feature } from "@vertigis/arcgis-extensions/data/Feature";
import type { FeatureSource } from "@vertigis/arcgis-extensions/data/FeatureSource";
import type { Command } from "../Command.js";
import { CommandRegistry } from "../CommandRegistry.js";
import type { Event } from "../Event.js";
import { EventRegistry } from "../EventRegistry.js";
import type { Operation } from "../Operation.js";
import { OperationRegistry } from "../OperationRegistry.js";
import type { Features, File, HasFeatures, HasGeometry, HasLayers, HasMaps, HasUITarget, MapsLike } from "../common.js";
import type { EditGeometryOptions } from "./sketching.js";
/**
 * Arguments for the "edit.add-attachment" command. Supported by both Web and
 * Mobile.
 */
export interface AddAttachmentArgs {
    /**
     * The map.
     */
    maps: MapsLike;
    /**
     * The feature(s) to add the attachment to.
     */
    features: Feature[];
    /**
     * The name of the attachment.
     */
    name: string;
    /**
     * The MIME content type of the attachment.
     */
    contentType: string;
    /**
     * The binary data for the attachment.
     */
    data: number[];
}
/**
 * VertiGIS Studio Web's arguments for the "edit.add-attachment" command. Not
 * supported by Mobile.
 */
export interface WebAddAttachmentArgs {
    /**
     * The feature(s) to add the attachment(s) to. If multiple features are
     * specified, the attachment(s) will be added to all features.
     */
    features: Features;
    /**
     * The blob(s) that contains the file attachment(s). If multiple attachments
     * are specified, all attachment will be added to the feature(s).
     */
    blobs: File | File[];
}
/**
 * Arguments for the "edit.delete-attachment" command.
 */
export interface DeleteAttachmentArgs {
    /**
     * The feature(s) to remove the attachment(s) from.
     */
    features: Features;
    /**
     * The attachment(s) to remove from the feature(s). This property can be
     * populated with the title(s) or ID(s) of the attachments(s). Any and all
     * matching attachments found on the input features will be deleted. Web
     * only.
     */
    attachments?: string[];
    /**
     * The attachment to remove from the feature(s). Mobile only.
     */
    gcxAttachment?: Attachment;
}
/**
 * Arguments for various attachment events.
 */
export interface AttachmentEventArgs {
    /**
     * The feature that had an attachment added/updated/deleted.
     */
    feature: Feature;
    /**
     * The attachment that was added/updated/deleted.
     */
    attachment: Attachment;
}
/**
 * A collection of options common to interactive feature editing sessions. Web
 * only.
 */
export interface EditOptions {
    /**
     * Whether to show UI notifications. Defaults to `true`.
     */
    showNotifications?: boolean;
    /**
     * The orientation of the template picker. Defaults to "vertical".
     */
    orientation?: "horizontal" | "vertical";
    /**
     * Whether to show titles on the template picker. Defaults to `true`.
     */
    showTitles?: boolean;
    /**
     * Whether to allow editing of feature geometry.
     */
    editGeometry?: boolean;
    /**
     * Whether to allow editing of feature attributes.
     */
    editAttributes?: boolean;
    /**
     * Whether to allow editing of feature attachments.
     */
    editAttachments?: boolean;
    /**
     * Options for the geometry editing session.
     */
    editGeometryOptions?: EditGeometryOptions;
    /**
     * Web only. Additional settings that are specific to sketching plugins,
     * keyed by plugin ID. The only currently supported plugin is "snapping". A
     * boolean value can also be assigned to completely disable, or enable with
     * default settings.
     */
    pluginSettings?: Record<string, boolean | Record<string, unknown>>;
}
/**
 * Used to update an in-progress interactive feature editing session with new
 * attributes, attachments or geometry. Web only.
 */
export interface UpdateSessionArgs extends HasGeometry {
    /**
     * A collection of attributes that apply or are to be applied to the
     * currently edited feature.
     */
    attributes?: Record<string, string | number>;
    /**
     * A collection of attachments that apply or are to be applied to the
     * currently edited feature.
     */
    attachments?: Attachment[];
}
/**
 * Arguments for the "edit.create-feature" operation. A valid feature layer,
 * subtype group layer, or subtype sublayer is required. The geometry is
 * required for non-tabular features. Web only.
 */
export interface CreateFeatureArgs extends HasGeometry, HasLayers, HasMaps {
    /**
     * Whether to show UI notifications. Defaults to `true`.
     */
    showNotifications?: boolean;
    /**
     * The orientation of the template picker. Defaults to "vertical".
     */
    orientation?: "horizontal" | "vertical";
    /**
     * Whether to show titles on the template picker. Defaults to `true`.
     */
    showTitles?: boolean;
    /**
     * A collection of attributes to apply to the new feature.
     */
    featureAttributes?: Record<string, unknown>;
    /**
     * The template to use as a starting point for this feature. Requires a
     * layer. The default or first template will be used if not set.
     */
    templateName?: string;
    /**
     * A type id to use as a starting point for this feature. This may return
     * one or more templates and requires a layer with types defined.
     */
    typeId?: string;
}
/**
 * Arguments for the "edit.display-add-feature" command. Web only.
 */
export interface DisplayAddFeatureArgs extends CreateFeatureArgs, HasMaps, EditOptions {
    /**
     * Arguments for the display of the attribute editing form. Web only.
     */
    formUITarget?: HasUITarget;
    /**
     * Arguments for the display of the template picker. Web only.
     */
    templateUITarget?: HasUITarget;
    /**
     * A collection of configuration overrides for the editable fields. Web
     * only.
     */
    fieldElements?: FieldElementOverride[];
}
/**
 * Arguments for the "edit.display-add-related-feature" command. A feature and a
 * relationship ID are supplied as inputs instead of a layer.
 */
export interface DisplayAddRelatedFeatureArgs extends Omit<DisplayAddFeatureArgs, "layers">, HasFeatures {
    /**
     * The ID of the relationship to add a feature to.
     */
    relationshipId: string;
    /**
     * The feature source for the related feature to create. Mobile only.
     */
    relatedFeatureSource: FeatureSource;
}
/**
 * Arguments for the "edit.display-update-features" operation. Web only.
 */
export interface DisplayUpdateFeatureArgs extends EditCommandArgs, HasGeometry, HasMaps, HasUITarget, EditOptions {
    /**
     * A collection of attributes to automatically apply to the updated feature.
     */
    featureAttributes?: Record<string, unknown>;
    /**
     * A collection of configuration overrides for the editable fields.
     */
    fieldElements?: FieldElementOverride[];
}
/**
 * Arguments for the "edit.add-features", "edit.update-features" and
 * "edit.delete-features" commands. Web only.
 */
export interface EditCommandArgs extends HasFeatures {
    /**
     * Whether to show UI notifications. Will default to `true`.
     */
    showNotifications?: boolean;
}
/**
 * Arguments for the "edit.bulk-attribute-update" command. Web only.
 */
export interface BulkAttributeUpdateArgs extends HasFeatures {
    /**
     * The attributes to update on all features.
     */
    attributes: Record<string, unknown>;
}
/**
 * Result of a bulk attribute validation. Web only.
 */
export interface ValidationResult {
    /**
     * Whether this validation passed or failed.
     */
    isValid: boolean;
    /**
     * Optional validation message or error details.
     */
    message?: string;
}
/**
 * Arguments for bulk attribute validation events. Web only.
 */
export interface BulkAttributeValidationEventArgs extends HasFeatures {
    /**
     * Array of validation results from different validators. The bulk edit
     * operation is considered valid only if all results are valid.
     */
    validationResults: ValidationResult[];
}
/**
 * Arguments for bulk attribute completion event. Web only.
 */
export interface BulkAttributeCompleteEventArgs extends HasFeatures {
    /**
     * Whether the bulk attribute update was successful.
     */
    success: boolean;
    /**
     * Optional error message if the update failed.
     */
    error?: string;
}
/**
 * Arguments for bulk attribute pre-validation event. Web only.
 */
export interface BulkAttributePreValidationEventArgs extends HasFeatures {
    /**
     * The attributes that will be applied to the features.
     */
    attributes: Record<string, unknown>;
}
/**
 * Override settings for a field element.
 */
export type FieldElementOverride = Partial<FieldElement>;
export declare class EditCommands extends CommandRegistry {
    protected readonly _prefix = "edit";
    /**
     * Create and add an attachment to a provided feature, using the given
     * attachment data.
     */
    get addAttachment(): Command<AddAttachmentArgs | WebAddAttachmentArgs>;
    /**
     * Deletes attachments from feature(s).
     */
    get deleteAttachment(): Command<DeleteAttachmentArgs>;
    /**
     * Adds a feature to a particular layer. `Features` and `EditCommandArgs`
     * are not supported on Mobile.
     */
    get addFeature(): Command<Feature | Features | EditCommandArgs>;
    /**
     * Cancels active editing sessions and discards any changes. If a feature is
     * supplied only the sessions using that feature will be cancelled. Web
     * only.
     *
     * @webOnly
     */
    get cancel(): Command<Features>;
    /**
     * Completes active editing sessions and submits any changes made to the
     * attributes, attachments or geometry to the feature source. If a feature
     * is supplied, only sessions using that feature will close. Web only.
     *
     * @webOnly
     */
    get complete(): Command<Features>;
    /**
     * Deletes the given feature or features from their feature sources.
     * `EditCommandArgs` is not supported on Mobile.
     */
    get deleteFeatures(): Command<Features | EditCommandArgs>;
    /**
     * Begin an interactive feature editing session with a new feature.
     * `DisplayAddFeatureArgs` is not supported on Mobile.
     *
     * **Example:** Create and allow the user to edit a new feature with an
     * initial attributes collection. If no geometry is provided in context they
     * will be asked to select one.
     *
     * _Note:_ $map1.map.extension is the output of a 'Get Map' activity run in
     * Web by Workflow. When the map and/or layer are provided in the context of
     * a command chain these parameters can be omitted.
     *
     * ```
     * {
     *     "editAttributes": true,
     *     "editGeometry": true,
     *     "featureAttributes": {
     *         "ASSET_ID": "WFH001234"
     *     },
     *     "layers": "Victoria_Fire_Hydrants_8780",
     *     "maps": $map1.map.extension
     * }
     * ```
     */
    get displayAddFeature(): Command<FeatureSource | DisplayAddFeatureArgs>;
    /**
     * Begin an interactive feature editing session for a new related feature.
     * The specified feature will be the original feature that the new related
     * feature will be added to in the relationship.
     *
     * **Example:** Create and edit a new record on a related table, with the
     * option to add attachments. Make sure the 'COMMENTS' field is included in
     * the editable attributes and make it required.
     *
     * _Notes:_.
     *
     * 1. The feature used here must come from the running viewer, and cannot be an
     *    ad-hoc feature created from a JSON object. For example, you can use
     *    the output of `results.get-active-features`, or the feature provided
     *    in a command chain context.
     * 2. `editableExpression` and `requiredExpression` both take an arcade
     *    expression, and here the string "true" is just a simple arcade
     *    expression that always returns true. You can also use a more complex
     *    expression, or reference one from your webmap.
     *
     * ```
     * {
     *     "editAttributes": true,
     *     "editAttachments": true,
     *     "features": $runOperation1.result,
     *     "relationshipId": "1",
     *     "fieldElements": [
     *         {
     *             "fieldName": "COMMENTS",
     *             "editableExpression": "true",
     *             "requiredExpression": "true"
     *         }
     *     ]
     * }
     * ```
     */
    get displayAddRelatedFeature(): Command<DisplayAddRelatedFeatureArgs>;
    /**
     * Begin an interactive feature editing session with an existing feature.
     * `DisplayUpdateFeatureArgs` is not supported on Mobile.
     */
    get displayUpdateFeature(): Command<Feature | DisplayUpdateFeatureArgs>;
    /**
     * Updates a layer feature or features. Edits to the geometry and attributes
     * of the supplied features will be committed to their respective feature
     * sources. `Features` and `EditCommandArgs` are not supported on Mobile.
     */
    get updateFeature(): Command<Feature | Features | EditCommandArgs>;
    /**
     * Updates an in-progress interactive feature editing session with new
     * attributes, attachments, or geometry. These will be immediately applied
     * to the current session, if one is active. Web only.
     *
     * @webOnly
     */
    get updateSession(): Command<UpdateSessionArgs>;
    /**
     * Updates multiple features from multiple sources simultaneously. This
     * command commits the bulk attribute changes directly to the feature
     * source. Web only.
     *
     * @webOnly
     */
    get bulkAttributeUpdate(): Command<BulkAttributeUpdateArgs>;
    /**
     * Clears a feature's GNSS metadata. This command will clear the well known
     * GNSS attributes, such as "esrignss_longitude" and "esrignss_latitude".
     *
     * @mobileOnly
     */
    get clearGnssMetadata(): Command<Feature>;
}
export declare class EditOperations extends OperationRegistry {
    protected readonly _prefix = "edit";
    /**
     * Creates a new feature for the supplied feature source from the supplied
     * configuration. This operation does not add the feature to the source, but
     * returns the feature for further processing. Web only.
     *
     * @webOnly
     */
    get createFeature(): Operation<CreateFeatureArgs, HasFeatures>;
    /**
     * Automatically populates the well known GNSS attributes from the current
     * location data. Examples of well known GNSS attributes are
     * "esrignss_longitude" and "esrignss_latitude". The input feature argument
     * may be null, in which case a new feature will be created. Returns the
     * input feature, or a new feature if one was created.
     *
     * @mobileOnly
     */
    get updateGnssMetadata(): Operation<Feature, Feature>;
}
export declare class EditEvents extends EventRegistry {
    protected readonly _prefix = "edit";
    /**
     * Raised when an attachment is added to a feature. Mobile only.
     *
     * @mobileOnly
     */
    get attachmentAdded(): Event<AttachmentEventArgs>;
    /**
     * Raised when an attachment is updated. Mobile only.
     *
     * @mobileOnly
     */
    get attachmentUpdated(): Event<AttachmentEventArgs>;
    /**
     * Raised when an attachment is deleted from a feature. Mobile only.
     *
     * @mobileOnly
     */
    get attachmentDeleted(): Event<AttachmentEventArgs>;
    /**
     * Raised before bulk attribute update validation occurs, allowing for
     * modifications to the features. Web only.
     *
     * @webOnly
     */
    get bulkAttributeUpdatePreValidation(): Event<BulkAttributePreValidationEventArgs>;
    /**
     * Raised when bulk attribute update validation is complete. Web only.
     *
     * @webOnly
     */
    get bulkAttributeUpdateValidation(): Event<BulkAttributeValidationEventArgs>;
    /**
     * Raised when a bulk attribute update is complete. Web only.
     *
     * @webOnly
     */
    get bulkAttributeUpdateComplete(): Event<BulkAttributeCompleteEventArgs>;
    /**
     * Raised when a new feature is added to a feature source.
     */
    get featureAdded(): Event<Feature>;
    /**
     * Raised when a feature is deleted from a feature source.
     */
    get featureDeleted(): Event<Feature>;
    /**
     * Raised when the attributes or geometry of a feature from a feature source
     * are updated.
     */
    get featureUpdated(): Event<Feature>;
    /**
     * Raised when an interactive feature editing session is updated with new
     * attributes, attachments, or feature geometry. The payload of this event
     * represents the current state of that session and has not yet been applied
     * to the feature. Web only.
     *
     * @webOnly
     */
    get sessionUpdated(): Event<UpdateSessionArgs>;
}