Developing Web Applications with the Web ADF - Web controls  

EditorTask control



The EditorTask control provides a suite of tools for Web-based editing of feature layers in ArcGIS Server map services. The runtime dialog provides tools to modify, add, and remove feature geometry and attributes.  The EditorTask can also be customized and extended to filter attributes, manage tools, handle events during the editing process, and manage panels.  See the discussion section below for more details.

The following set of requirements apply to the EditorTask capabilities:  
Assembly: ESRI.ArcGIS.ADF.ArcGISServer.Editor.dll
Class: ESRI.ArcGIS.ADF.ArcGISServer.EditorTask
JavaScript libraries: display_common.js, display_dotnetadf.js, display_editortask.js, display_editorSnapTip.js, display_contextmenu.js, display_floatingpanel.js, display_task.js, display_toolbar.js
Using the EditorTask control
  1. Add supporting controls to the page

    In order to take use the EditorTask control, a number of supporting controls must be available.  Set up a Web application with, at minimum, a  MapResourceManager control and a Map control using their discussion topics as a guide. Other controls may optionally be added, such as a Toolbar control for zooming and panning operations.
  2. Add the EditorTask control to the page

    Drag an EditorTask control onto the page. For the purposes of this example, the EditorTask does not need to be contained within a TaskManager control. If using the Web Mapping Application template, a TaskManager is used to handle the opening of the task from the left-hand console list of tasks. The page does not need a TaskResults control, since the EditorTask does not actually create results output. The EditorTask inherits from FloatingPanel, so that it will automatically appear in a floating window at run time.

    Your page should resemble the following in Visual Studio:

    Visual Studio with EditorTask

  3. Set the properties for the EditorTask control

    You must set a few of the properties of the EditorTask in order for it to work properly. You may access the required properties from the "smart tag" which you can open by hovering over the right side of the EditorTask control. Click the arrow to expand the smart tag menu. EditorTask smart tags

    Alternatively, you can set the properties using the Properties window for the control:

    EditorTask properties

    a. Select Resource to Edit: Click this item in the smart tag list of tasks, or in the Properties window, click the ellipsis button for the MapResource property. This displays the Select Map Resource Editor dialog:

    Select map resource dialog

    In the resource editor, click the drop-down list to select the Map control added earlier. Select a service from the Resource drop-down list. If no services appear in this list, check that an ArcGIS Server Local resource is present in the MapResourceManager, and that the resource is a non-pooled service.

    b. Select Editable Layers: Click this item in the smart tag list of tasks in the EditorTask control, or in the Properties window, click the details button for the EditableLayers property. This displays the Select Editable Layers Editor dialog. It may take some time for the dialog to find the editable layers, during which time the dialog is grayed out. Once the available layers are found, the dialog should appear similar to the following:

    EditorTask layers

    If no layers appear in the list, check that the map service is using ArcSDE layers. If multiple ArcSDE databases have been added to the map service, use the Database drop-down list to select the one you want to use. Also, if a versioned geodatabase is used in the map service, you may select either to edit as versioned or as unversioned. If you select unversioned, only layers not set as versioned may be enabled for editing.

    The left-hand column, labeled "Layers not available for editing", lists layers that you can enable for editing by users. Click a layer to highlight it, and click the >> button to move it to the list of Editable Layers on the right side of the dialog. Only layers in the Editable Layers list will be available for users to edit.

    c. Select Editable Versions : You need to set this item if using a versioned ArcSDE database. If editing an unversioned database, this option is not available. To select versions, click the Select Editable Versions item in the smart tag list, or in the Properties window, click the details button for the VersionIDs property. This displays the Select Editable Versions Editor:



    Available versions are listed in the left hand side of the dialog. To make versions available to users, click a version in the left side, then click the >> button to move it to the right side list of Editable Versions. Only versions appearing in the right-hand list are available to users.

    d. Set Snapping Rules: By default, no snapping is used when editing. Snapping forces a click near an existing feature to be set exactly at a part of the nearby feature. This allows features to exactly coincide along their borders. To add snapping to the application, click the Set Snapping Rules item in the smart tag list, or in the Properties window, click the details button for the Snapping property. This displays the Set Layer Snapping Editor:



    This dialog displays all layers that may be enabled for editing, even if the layers have not been actually added to the editable layers list. This is because snapping can occur across layers. For example, if you enable snapping to a parcels layer and are adding a new building feature, new vertices may be snapped to a parcel within the snapping tolerance.

    Three snapping types are available: edge, where snapping can occur anywhere along a feature; vertex, where snapping occurs to x,y points defining the shape of a feature; and end , where snapping occurs to the endpoints of a feature. For more information on snapping types, consult the ArcGIS Desktop Help.

    e. Optional: Change other properties for editing

    Other properties for editing may be set in the Properties window for the Editor Task.  Refer to the Properties section below to change EditorTask properties at design-time.
     
  4. Add an ArcGIS Identity

    Applications using an ArcGIS Server Local resource must contain an ArcGIS identity to enable use of the resource. To add an identity, right-click on the Web application in the Solution Explorer, and click Add ArcGIS Identity. A dialog displays where you can enter the user name, password, and domain or machine name. Click OK to insert the identity, which is stored in the web.config file of the application.

    If an appropriate identity is not added to the application, the user may see an error when starting the Web application, such as one saying that "an object reference is not set to an instance of an object."
  5. Using the EditorTask at runtime

    For details about using the editor task, see the Help system for the Web Mapping Application, under the page "Editing Data". You can obtain a copy of this Help by creating a new website from the Visual Studio menu under File-New-Website, and choosing the "Web Mapping Application" template. You can also generate a new website from the ArcGIS Server Manager or ArcIMS Web Manager. In either case, a Help folder will be included in the website. The editor task help may be brought up from the main Help page (default.htm), or it can be viewed directly at the EditorTask.htm page.

Members

Properties


  The following tables provide a list of properties and events of interest.  For complete reference information, see the EditorTask control in the library reference section.

Property Name  Type Description
ConflictLevel ConflictLevel How conflicts are defined. Either when a second user edits the same feature (Row), or only when editing the same attributes of a feature (Column).
Conflict Resolution ConflictResolution Whether conflicting features are replaced by their representations in the target version or the current edit session.
CreateNewFeatureTitle string  Text title for the section for creating new features.
EditableLayers A list of the layer IDs for all layers that will be editable by the editor
EditAttributesTitle string Text title for the section for editing feature attributes.
EditExistingFeatureTitle string Text title for the section for modifying the geometry and position of features.
EditorSettingsTitle string Text title displayed in the section for changing edit settings for snapping and feature selection.
EnableChangeSettings bool Whether to allow the user to change edit settings for snapping and feature selection.
EnableEditAttributes bool Whether to allow the user to change attributes of features.
EnableEditExistingFeature bool Whether to allow the user to modify the geometry or position of existing features.
EnableNewFeatureCreation bool Whether to allow the user to add new features.
FeatureHighlightColor Color The color to use for highlighting the feature selected for attribute editing.
FeatureSelectionColor Color Color to highlight features when selected by the user.
FeatureSelectionMode FeatureSelectionMode How features are to be selected with the SelectFeature tool.
MapResource string The map resource to be edited.
NotifyOnConflicts bool Whether to display a notification message when conflicts are detected and resolved while saving edits.
SelectionLimit int Maximum number of features selectable by the user.
SelectionTolerance int When selecting, features within this number of pixels of a click will be selected.
ShowFeatureHighlight bool Indicates if the feature whose attributes are shown in the attribute editor panel should be highlighted.
ShowSnapCircle bool Whether to display a circle around the cursor that indicates the snapping distance.
Snapping StringList The snapping rules to use while editing.
SnapTipColor Color When the user is using a tool with snapping enabled, and presses the 's' key, a marker will be displayed with this color at the location that will be snapped to.
SnapTolerance int Pixel distance within which snapping to a feature will occur.
TaskResultsContainers BuddyControlCollection The controls in which results from this task are displayed.
Title string Text displayed in the main title of the editor task window.
VersionIDs StringList A list of all of the versions that will be editable by the editor. If the editable layers are non-versioned, then this property is ignored.
VertexColor Color Color of vertices when displayed by the user.

Events

EditorTask Event Type Description
EditorPanelsCreated Occurs when the editor panels (create feature, edit feature, edit attribute) are created.   Can be used to add a custom panel to the main EditorTask panel. 
PostAttributeEdit This event is fired when an attribute edit has completed.
PostCommandExecute An Editor command completed execution of its server action.
PostToolExecute An Editor tool completed execution of its server action.
PreAttributeEdit This event is fired when an attribute edit is about to be made.  It may be used for input validation or cancellation of the edit.
PreCommandExecute  An Editor command is about to execute its server action.
PreToolExecute An Editor tool is about to execute its server action.  This would allow developers to target specific edits and possibly abort based on their own criteria or add their own logging.
SettingsPanelsCreated  Occurs when the settings panel is created (when the Settings link in the main EditorTask panel is clicked).   Can be used to add a custom panel to the Settings panel.
SetVersion Fired when the end-user selects a version from the version list.  The version of the layers in the workspace being edited are set to the selected version.
ToolsCreated Occurs when the tools in an existing toolbar, in an Editor panel, are created.  Can be used to add a custom tool to an existing toolbar.

Editor Event Type  Description
LayerChanged Occurs when the current edit layer changes via the drop down list in the Editor or when setting the geodatabase version.  Can be used to interact with the edit layer via the ArcObjects IFeatureLayer interface.


Event Arguments

EditorTask Event Argument Type  Description
EditorPanelsCreatedEventArgs Created when the EditorPanelsCreated event occurs.  Provides access to the existing panels on the main EditorTask panel.
PostAttributeEditEventArgs Created when the PostAttributeEdit event occurs.  Provides access to the feature and dataset that was edited.
PostCommandExecuteEventArgs Created when the PostCommandExecute event occurs.  Provides access to the editable feature layer and server context.
PostToolExecuteEventArgs Created when the PostToolExecute event occurs.  Provides access to the editable feature layer and server context.
PreAttributeEditEventArgs Created when the PreAttributeEdit event occurs.  Provides access to the feature and dataset being edited.
PreCommandExecuteEventArgs Created when the PreCommandExecute event occurs.  Provides access to the editable feature layer and server context.
PreToolExecuteEventArgs Created when the PreToolExecute event occurs.  Provides access to the editable feature layer and server context.
ToolsCreatedEventArgs Created when the ToolsCreated event occurs.  Provides access to the toolbars in the EditorTask.

Discussion
    1. Using the out-of-the-box EditorTask, add custom functionality by handling EditorTask events in a page.
    2. Create a custom Web control by subclassing the EditorTask and its child controls.
    Option 1 is designed for convenient access to standard EditorTask events in a Web application.   Option 2 is more complex, but provides comprehensive access to the implementation details (which includes events) of the EditorTask and its subcomponents.   It also enables you to package a Web ADF editing solution as a redistributable custom EditorTask control.   In either case, it is important to understand the existing structure of an EditorTask.   At run-time the EditorTask creates two visible container controls: the Editor and EditorSettingsPanel.  The Editor is a composite control that contains either a VersionIDPanel or a set of editor panels and other controls to edit feature layers.  The EditorSettingsPanel is a type of EditorPanel that contains a SnappingPanel and SelectionPanel.     The class type and naming of these components will be important when working with EditorTask events or subclassing them in a custom EditorTask control.  
      
    Panel Structure and Naming

    This section provides a visual guide to the class type and unique control id for notable components packaged with the EditorTask.  For each component, the class type is listed above the unique control id, listed in quotes.

    If an editable layer is versioned and more than one version is available for editing, the VersionIDPanel will be displayed in the Editor when the EditorTask is initialized at runtime. 

    Visual Studio with EditorTask


    The EditorTask contains an Editor which represents the primary visible control that contains other editing controls.  The Editor contains a drop down list to select an editable layer.   The main toolbar contains a set of tools and commands to manage the selected features in the active edit layer.  A set of commands to manage edit operations may be included depending on the type of layer being edited and the map service in which it is accessed.   When editing a non-versioned feature layer in a pooled service, the main toolbar will not contain an Undo, Redo, or Save button.  When editing non-versioned data in a non-pooled service, the Undo and Redo buttons will not be available.  The main toolbar can be customized.

    The Editor also contains a set of panels to create and modify features and attributes.    The CreateFeaturePanel contains one or more tools to create a new feature depending on the active edit layer feature type.   It contains a toolbar that cannot be customized.  The EditExistingFeaturesPanel contains a number of tools and commands to modify existing features.  It contains two toolbars; GeometryToolbar1 contains items to modify entire features while items in GeometryToolbar2 were designed to manipulate feature vertices.  Both toolbars can be customized.   The EditAttributesPanel lists the attributes of the current set of selected features.  Since only one feature's attributes can be visible at any time, paging will be enabled when more than one feature is selected.  The visibility and editability of attributes can be modified via attribute filtering (see discussion below).  The attribute labels and textboxes are generated internally by the EditAttributesPanel and are not available for explicit customization.   

     Visual Studio with EditorTask

    The EditorTask also contains an EditorSettingsPanel which can be initialized via the Editor at runtime and is designed to compliment actions initiated by Editor panels.  The EditorSettingsPanel contains two panels: a SnappingPanel and SelectionPanel.  The SnappingPanel panel provides the ability to change snapping rules and snap tips display at runtime.  The SelectionPanel provides the end user with the ability to modify selection behavior when using the select tool in the Editor's main toolbar.  Both panels are not designed to be customized.  However, like the Editor, the EditorSettingsPanel is designed to add or remove panels.    

    Visual Studio with EditorTask


    Customization Categories

    The EditorTask was explicitly designed to support customization in the following distinct, but related categories:

Recall that there are two options for developing a custom EditorTask solution; handle events on an out-of-the-box EditorTask control or subclass the EditorTask and its subcomponents.  Both options will be discussed within the context of each category.  A comprehensive sample is also included in this help system: Common_CustomEditorTask

Option 1 uses an out-of-the-box EditorTask control and EditorTask events within the context of the page\control lifecycle to implement custom capabilities in each category. The diagram below highlights where these categories can be leveraged with option 1. Note that you can add event handlers during Page or EditorTask control lifecycle events (e.g Init, Load).
Visual Studio with EditorTask


Option 2 demonstrates how to subclass existing EditorTask controls, override members, create new custom components, and construct a redistributable EditorTask component.   All customization capabilities present in option 1 are available with option 2, plus those capabilities that are only available within a subclass solution (e.g. protected members).  Note that instead of working with the event handler EditorTask and Editor events are now overridden in their respective subclass.  The diagram below highlights where the implementation of each customization category may occur when extending the EditorTask.
  
Visual Studio with EditorTask



EditorTask Events

Customizing an out-of-the-box EditorTask control will involve working with EditorTask events and event handlers.   EditorTask event methods can be overridden in a subclassed EditorTask, but are not explicitly necessary.   The diagrams included below list the event type, which EditorTask component triggers the event and when it is triggered (e.g. which method in the component).   It is important to note that the CreateChildControls() method for all components is called between control load an page prerender upon the initial request, and between page init and page load during every postback\callback.  


  Visual Studio with EditorTask

Attribute Filtering 

The EditorTask can be customized to filter attributes available for editing at runtime.  The EditorTask has a property named AttributeDisplay which is a collection of AttributeDisplayInfo objects.  The AttributeDisplayInfo class allows you to define how attributes are displayed for a specific layer using the DisplayMode enumeration.  DisplayMode is defined as follows:

DisplayMode Enum  Description
Editable The attribute is displayed and editable.
ReadOnly The attribute is shown as read-only (text in the textbox is grayed-out).
Hidden The attribute is not shown.

The AttributeDisplayInfo class enables you to do two things:

1) Specify how attributes are displayed by default.
2) Define how specific fields are to be displayed using the Add method.

If you only want to display a few attributes, you can set the default display mode to “Hidden” (via the constructor or DefaultDisplayMode property) and explictly list the fields you want to display. Conversely, if you have many attributes and only want to hide a few, set DefaultDisplayMode to “Editable” or "ReadOnly" and then turn off the fields you want to hide.   Here is a sample code snippet to illustrate filtering attributes on a layer using AttributeDisplayInfo.  For customization option 1 (out-of-the-box EditorTask), filter attributes during initial Page Load or add an event handler on the EditorTask OnLoad event.  For option 2 (custom EditorTask subclass), override the OnLoad event of the custom EditorTask class and filter attributes when the control is first loaded.   

[C#]