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 applies to the EditorTask capabilities:  

• The EditorTask requires an ArcGIS Server Local map service.  
• The ArcGIS Server map service can be either pooled or non-pooled.
• The map service must host an MXD map document, MSD based services are not supported. 
• Both versioned and non-versioned layers can be edited in non-pooled services, while only non-versioned layers can be edited in pooled services.
  
  At runtime, the Editor panel contains a set of sub panels which contain different items depending on the purpose and feature type being edited.  Editing non-versioned data will change the availability of some commands on the Editor panel.  When using non-versioned data with a pooled service, the Editor panel will not contain a Undo, Redo, or Save button for pooled services.   When using non-versioned data with non-pooled service, the Undo and Redo button will not be available.   Undo and Redo are capabilities of a versioned geodatabase.  The Save option is a capability defined by a non-pooled service.     
  
• While the map service can contain many different data types, editable layers for the EditorTask must be ArcSDE enterprise or workgroup layers. 
• Shapefiles and personal geodatabases cannot be edited with the EditorTask, but they can be used for other operations such as snapping. 
• The data frame in the map service that contains an editable layer cannot be projected on the fly by the Web ADF or projected within the mxd.  
• If more than one feature layer share the same name in a map service, only one is editable.  It is recommended that each editable layer in a map service have a unique layer name.

Assembly: ESRI.ArcGIS.ADF.ArcGISServer.Editor.dll
Class: ESRI.ArcGIS.ADF.ArcGISServer.EditorTask

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:
   
   
   
   
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.
   
   Alternatively, you can set the properties using the Properties window for the control:
   
   
   
   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:
   
   
   
   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 references a service that hosts an MXD map document (MSD based services are not supported).  
   
   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:
   
   
   
   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. 
   
   
   
4. Optional: Filter Attributes for display and interaction
   
   You can use the AttributeDisplay property to define which fields in each editable layer are hidden, read-only or editable at runtime.   In Visual Studio, click on the ellipsis next to the AttributeDisplay property in the property window to display the follow dialog.  Select from the editable layers to display the layer fields.  The visual interface enables you to enable the appropriate properties on each field.  By default, all fields are editable. 
   
   
    
5. 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."
   
6. 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.  Note, the EditorTask may create ADF graphics layers to manage client interaction at runtime.  Keep this in mind when traversing the map resources being used by the Map. 

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.

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

• Customizing the EditorTask
  
  While the EditorTask includes a comprehensive set of out-of-the-box capabilities, many Web editing solutions will require customizing the behavior of the EditorTask to satisfy user specific requirements.  The EditorTask offers two options for developing a custom solution:
  

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. 




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.   

 

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.    






Customization Categories

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


• EditorTask events
• Attribute Filtering
• Custom Editor Toolbars and Toolbar Items 
• Custom Editor Panels

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).



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.
  




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.  


  

• EditorPanelsCreated
  
  This event is triggered after the panels in the Editor are created during the CreateChildControls() method.    Three panels are created: a CreateFeaturePanel, an EditExistingFeaturePanel, and an EditAttributesPanel panel.   The event argument (EditorPanelsCreatedEventArgs) references a collection of panels.  See the section on Custom Editor Panels below for more details. 
  
• SettingsPanelsCreated
  
  This event is triggered after the panels in the EditorSettingsPanel are created during the CreateChildControls() method.   Two panels are created: SnappingPanel and SelectionPanel.  The event argument (EditorPanelsCreatedEventArgs) references a collection of panels and can be used to add\remove or modify panels.  See the section on Custom Editor Panels below for more details.  
    
• ToolsCreated
  
  This event can be triggered twice per request, once when the toolbar in the Editor control is created and again when the toolbars in the EditExistingFeaturePanel are created.   The Editor control contains one toolbar with the id "MainToolbar".  The EditExistingFeaturePanel contains two toolbars: "GeometryToolbar1" and "GeometryToolbar2".  Note that the CreateFeaturePanel contains a toolbar, but it cannot be customized.   Handle this event to remove\modify toolbar items on an existing toolbar, add new toolbar items, remove toolbars, or add new toolbars.   Only toolbars and tools in the Editor and EditExistingFeaturePanel can be modified.  The event argument (ToolsCreatedEventArgs) references the container, Editor or EditExistingFeaturePanel, via the Parent property.  The Toolbars property contains a collection of toolbars in the respective parent.  See the section on Custom Editor Tools for more details.
  
• SetVersion
  
  This event is triggered via a postback\callback when a geodatabase version is selected in the VersionIDPanel.  Handle this event to change EditorTask content or behavior based on a specific version.   The event argument (SetVersionEventArgs) merely returns the selected version string.
  
• LayerChanged   
  
  This event is unique because the event handler is exposed on the Editor, not the EditorTask.  It can be triggered via a postback\callback initiated by two actions in an Editor: when a geodatabase version is selected in the VersionIDPanel and when a layer is selected in the layer drop down list at the top of the Editor after a version has been selected.  Handle this event to get a reference to the active editable feature layer and modify EditorTask behavior or prepare the feature layer for editing.  The event argument (IFeatureLayer) provides access to the ArcObjects feature layer and feature class.    
  
  
  
  
  
• PreAttributeEdit
  
  This event is triggered when the value in a textbox in the EditAttributesPanel is changed and the textbox loses focus.  A callback to the EditAttributesPanel calls the SaveEdit() method.   Note, the SaveEdit() method cannot be overridden.  The PreAttributeEdit event is triggered before an edit operation is initiated, namely a call to the ArcObjects IWorkspaceEdit.StartEditOperation().  Handle this event to modify the user provided attribute value or update other attributes during the same operation.   The event argument (PreAttributeEditEventArgs) provides access to the IFeatureLayer, IFeature, and IField being edited and the new attribute value.  You can also cancel the edit operation at this point by setting the Cancel property to true. The event also maintains the ReturnMessage property to send a message to the client in an alert box.
  
• PostAttributeEdit
  
  Like the PreAttributeEdit event, this event is triggered when the value in a textbox in the EditAttributesPanel is changed and the textbox loses focus.  A callback to the EditAttributesPanel calls the SaveEdit() method.   The PostAttributeEdit event is triggered after an edit operation has occurred, namely after a call to the ArcObjects IWorkspaceEdit.StopEditOperation().  Handle this event to modify information presented to the user or updated other related server-side content. The event argument (PostAttributeEditEventArgs) provides access to the IFeatureLayer, IFeature, IField and the new value that was used in the edit operation.   You can also check to see if the operation was successful and if not, interrogate the exception.  The event also maintains the ReturnMessage property to send a message to the client in an alert box.
   
  
  
  
• PreCommandExecute
  
  This event is triggered when pressing a button in a toolbar in the EditorTask that initiates a callback to the Web application.  The implementation code for the command is in a class that inherits from EditorServerCommandAction.   A callback to the Toolbar control (may be an EditorToolbar) calls the EditorServerAction() method in the custom command action class.  Note that the EditorServerCommandAction class is associated with a Toolbar control via an EditorCommand, a type of toolbar item. 
  
  The PreCommandExecute event is triggered before the EditorServerAction() method is executed.  Handle this event to check edit layer properties or work with other content in the map service.  This event is especially useful if you do not have access to the command source code or need to initiate the same set of actions before any one of a group of commands execute.  The event argument (PreCommandExecuteEventArgs) provides access to the ServerAction class (EditorServerCommandAction class) which references a number of useful properties.  The IMap, IMapServer, and server context of the map service associated with the command action are available.  The ArcObjects IDataset and SOAP LayerDescription for the active edit layer are also provided.  The ToolbarItemInfo property returns information about the EditorCommand toolbar item.   Use the Editor property to get a reference to the Editor control.  With the Editor control you can interact with current edit session properties, such as the active edit layer name, the MapFunctionality or MapResource associated with the EditorTask, or add custom CallbackResults to the callback response.   You can also cancel the command by setting the Cancel property to true. The event also maintains the ReturnMessage property to send a message to the client in an alert box.
  
• PostCommandExecute
  
  Like the PreCommandExecute event, this event is triggered when pressing a button in a toolbar in the EditorTask and the implementation code is in a class that inherits from EditorServerCommandAction.   
  
  The PostCommandExecute event is triggered after the EditorServerAction() method is executed.   Handle this event to perform post command processing on the active edit layer or other content in the map service.   The event argument (EditorCommandEventArgs) provides access to the ServerAction class which references a number of useful properties.  This event argument exposes the same properties as PreCommandExecuteEventArgs minus the Cancel option.
  
  
  
• PreToolExecute
  
  This event is triggered when applying a tool in a Map control associated with the EditorTask.  The implementation code for the tool action is in a class that inherits from EditorServerToolAction.   A callback to the Map control calls the EditorServerAction() method in the tool action class.  Note that the EditorServerToolAction class is associated with a Toolbar control via an EditorTool, a type of toolbar item.   
  
  The PreToolExecute event is triggered before the EditorServerAction() method is executed.   Handle this event to check edit layer properties, modify user provided input geometry, or work with other content in the map service.   The event argument (PreToolExecuteEventArgs) provides access to the ServerAction class (EditorServerToolAction class) which references a number of useful properties.  The IMap, IMapServer, and server context of the map service associated with the tool action are available.  The ArcObjects IDataset and SOAP LayerDescription for the active edit layer are also provided.  The ToolEventArgs provides access to the Map control in which the tool was applied; the same Map control that will generate a callback response.   It also exposes the user provided geometry in screen units.  The Geometry property on the event argument returns the ArcObjects geometry type in map units.   Use the Editor property to get a reference to the Editor control.  With the Editor control you can interact with current edit session properties, such as retrieving active edit layer name, the MapFunctionality or MapResource associated with the EditorTask, or refresh Editor content.  You can also cancel the command by setting the Cancel property to true. The event also maintains the ReturnMessage property to send a message to the client in an alert box.
  
• PostToolExecute
  
  Like the PreToolExecute event, this event is triggered when applying a tool in a Map control associated with the EditorTask.  The implementation code for the tool action is in a class that inherits from EditorServerToolAction.   A callback to the Map control calls the EditorServerAction() method in the tool action class.  Note that the EditorServerToolAction class is associated with a Toolbar control via an EditorTool, a type of toolbar item.   
  
  The PostToolExecute event is triggered after the EditorServerAction() method is executed.   Handle this event to confirm proper execution, initiate further actions, or work with other content in the map service.   The event argument (EditorToolEventArgs) provides access to the ServerAction class (EditorServerToolAction class) which references a number of useful properties.  This event argument exposes the same properties as the PreToolExecuteEventArgs minus the Cancel option.
  

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 explicitly 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#]

    protected void Page_Load(object sender, EventArgs e)
    {
        if (!Page.IsPostBack)
            FilterAttributes();
    }

    private void FilterAttributes()
    {
        AttributeDisplayInfo adi = new AttributeDisplayInfo(5, AttributeDisplayMode.Hidden);
        adi.Overrides.Add(new AttributeDisplayOverride("STATE_NAME", AttributeDisplayMode.ReadOnly));
        adi.Overrides.Add(new AttributeDisplayOverride("STATE_FIPS", AttributeDisplayMode.ReadOnly));
        adi.Overrides.Add(new AttributeDisplayOverride("SUB_REGION", AttributeDisplayMode.ReadOnly));
        adi.Overrides.Add(new AttributeDisplayOverride("POP1990", AttributeDisplayMode.ReadOnly));
        adi.Overrides.Add(new AttributeDisplayOverride("POP1999", AttributeDisplayMode.Editable));
        adi.Overrides.Add(new AttributeDisplayOverride("AVG_SALE87", AttributeDisplayMode.Editable));
        EditorTask1.AttributeDisplay.AttributeDisplayInfos.Add(adi);
    }
                    


Using the code above, here are the before and after screenshots of the EditorTask illustrating the changes in the attribute panel:




Custom Editor Toolbars and Toolbar Items

The out-of-the-box EditorTask includes a set of prepackaged toolbars and toolbar items available for use at runtime.   It also includes a set of custom components to support EditorTask specific behavior in toolbars, tools, and commands.     The prepackaged toolbars and toolbar items can be modified and new toolbars and toolbar items can be added.  In all cases, a toolbar in an EditorTask will reside in the Editor or an editor panel.  The technique for accessing and modifying these toolbars as well as adding new toolbars and toolbar items depends on the custom EditorTask solution (option 1 or 2).     

Two containers in the EditorTask expose toolbars for customization: the Editor and EditExistingFeaturePanel.   The Editor contains a toolbar named "MainToolbar" to manage selecting features and saving edits.  The EditExistingFeaturePanel contains two toolbars: "GeometryToolbar1" and "GeometryToolbar2".  "GeometryToolbar1" contains toolbar items to manage complete feature edits.  "GeometryToolbar2" contains toolbar items to manage feature vertex edits. 

If working with the out-of-the-box EditorTask (option 1), handle the ToolsCreated event to gain access to a list of toolbars and their parent.   The ToolsCreated event will be called twice for every request, once for the Editor and once for the EditExistingFeaturePanel.  Use the Parent property on the ToolsCreatedEventArgs event argument to retrieve the parent control in which the CreateToolbars() method was called.   Use the Toolbars property to return the toolbars in the parent.   Existing toolbars and toolbar items can be removed and custom toolbar items can be added to existing toolbars.   You can use the Toolbars property to add and reorder toolbars to the current parent container. 

If creating a custom EditorTask control (option2), override the CreateToolbars method in the custom Editor and/or EditExistingFeaturePanel.   In either case, call the base.CreateToolbars() method to return the default toolbars.  The CreateToolbars() method is called during the execution of the CreateChildControls() method.   Existing toolbars and toolbar items can be removed or modified while custom toolbars and toolbar items can be added.  In addition, custom toolbars and toolbar items can be added to existing or new editor panels by overriding and implementing the CreateChildControls() method, as is standard when creating any custom Web control.  

The EditorTask includes a set of custom classes and interfaces to use when creating toolbars and toolbar items for use within an EditorTask.   These classes and interfaces wrap existing Web ADF toolbar components and to be used within the events and operations specifically associated with the EditorTask.  Regardless of which customization option you choose, the same set of EditorTask components are available for use.   Most of the toolbar and toolbar item components enhanced for use with the EditorTask reside in the ESRI.ArcGIS.ADF.ArcGISServer.Editor.Tools namespace.


• Custom Editor Toolbar
   
  All toolbars included with the EditorTask (available in the Editor and EditExistingFeaturePanel) are a type of EditorToolbar.   The EditorToolbar class extends the Web ADF Toolbar in two ways.  First, it sets the toolbar group for all EditorToolbars to the same value "EditorToolbarGroup".  And second, it enables\disables toolbar items depending on the feature type and number of features selected in the active edit layer.   To take advantage of this capability a custom tool or command must be a type of EditorTool or EditorCommand (discussed below).  To create a custom toolbar, create a new instance of an EditorToolbar.  Set the ToolbarStyle, ID, and most importantly, the buddy control.   Set the buddy control to the Map control ID associated with the Editor so tools and commands in the toolbar will interact with the Map in which the EditorTask will edit data. 
    
  [C#]

  ESRI.ArcGIS.ADF.ArcGISServer.Editor.Tools.EditorToolbar newEditorToolbar =
    new ESRI.ArcGIS.ADF.ArcGISServer.Editor.Tools.EditorToolbar();
  
  newEditorToolbar.ToolbarStyle =
    ESRI.ArcGIS.ADF.Web.UI.WebControls.ToolbarStyle.ImageOnly;
  
  newEditorToolbar.ID = "MyCustomToolbar";
  
  newEditorToolbar.BuddyControlType =
    ESRI.ArcGIS.ADF.Web.UI.WebControls.BuddyControlType.Map;
  
  newEditorToolbar.BuddyControls.Add
    (new ESRI.ArcGIS.ADF.Web.UI.WebControls.BuddyControl(EditorTask1.Editor.MapID));
  						

• Custom Editor Tool
  
  A set of editor tools are included for use with the EditorTask.  The table below lists the class name and a description.  Note the class name is usually different that the edtior tool name.   For example, the EditExistingFeaturePanel included with the Editor task contains an EditorTool named "CopyPointFeature" whose ServerActionClass references the CopyFeature class.
  
  

  EditorServerToolAction class name	Description
  AddVertex	Add a vertex to the current selected features.  Included with GeometryToolbar2 in the EditExistingFeaturePanel.
  CopyFeature	Copy the current selected features.  Included with GeometryToolbar1 in the EditExistingFeaturePanel.
  CreateFeature	Create a new feature using the type defined by the active edit layer.  The CreateFeaturePanel includes a tool to create features based on the symbol classifications in the active edit layer.    This tool is generated internally by the CreateFeaturePanel - it does not use the CreateFeature tool.
  DeleteVertex	Delete a vertex in the current selected features.  Included with GeometryToolbar2 in the EditExistingFeaturePanel.
  MoveFeature	Move the current selected features.  Included with GeometryToolbar1 in the EditExistingFeaturePanel.
  MoveVertex	Move a vertex in the current selected features.  Included with GeometryToolbar2 in the EditExistingFeaturePanel.
  SelectFeature	Select features in the active edit layer.  Included with MainToolbar in the Editor.
  SplitFeature	Splits the selected set of features with a user defined line.  Included with GeometryToolbar1 in the EditExistingFeaturePanel.  Calls IFeatureEdit.SplitWithUpdate().
  TrimFeature	Cuts the selected set of features with a user defined line.  Not included in a out of the box toolbar.  Calls ITopologicalOperator3.Cut().

  
  When creating a custom tool for the EditorTask, subclass the EditorServerToolAction class and override the EditorServerAction method.   In general, the EditorServerToolAction class wraps your custom tool code for explicit use within the ArcObjects editing environment provided by the EditorTask.   The EditorServerToolAction class is built on the base class EditorServerActionBase, which provides access to the current Editor, and the ArcObjects server context, IMapServer, IMap, IDataSet, and the IFeatureLayer and ArcGIS Server SOAP LayerDescription for the feature layer being edited.   In addition, a set of methods are available to support customizing the initialization of the tool, modifying pre and post editing operations, changing error messages, refreshing the Editor and displaying the EditorTask AJAX indicator.  
  
  The EditorServerToolAction class provides a means for hooking into the pre and post tool execute event framework in the EditorTask.  To use this event framework, override the EditorServerAction method to include the custom implementation code for your custom editor tool.  This method will be called from within ServerAction in the EditorServerToolAction class - after the PreToolExecuteEvent and before the PostToolExecuteEvent.  During EditorServerAction method implementation, call the StartEditOperation() method before the edit takes place (e.g. IFeature.Store()), call StopEditOperation() after the edit occurs, and call AbortEditOperation() is an exception is thrown during the edit process.  All edit operation methods will enable\disable a workspace for editing.  Note, the EditorServerToolAction class also provides access to editor tool input, such as the user input geometry and whether snapping should be applied.   After tool execution, Editor toolbars will be refreshed (enable\disable save edits button), edit status will be updated (display a notice if there are unsaved edits),  and the EditorTask AJAX indicator will be hidden.  The following code illustrates an abbreviated example of the implementation code associated with a custom editor tool designed to clip selected features with a user provided envelope. 
   
  [C#]

  namespace CustomEditorTask_CSharp
  {
      class ClipFeatures : EditorServerToolAction
      {
          private List<int> features = new List<int>();
          public List<int> Features
          {
              get { return features; }
          }
  
          protected override void EditorServerAction()
          {
   	  IEnvelope agsCOMEnvelope = this.Geometry as IEnvelope
  	  . . .
  	  try
  	  {
  	    StartEditOperation();
  	    . . .
  	    agsCOMTopoOp3.Clip(agsCOMEnvelope);
  	    agsCOMFeature.Store();
  	    features.Add(agsCOMFeature.OID);
  	    . . .
  	    StopEditOperation();
  
  	  } catch (Exception e) {
  	    AbortEditOperation(e);
  	  }
  
  	  if (features.Count > 0)
  	  {
  	    Refresh(features, true);
  	  }
          }
      }
  }
  

  
  
  
  
  Wrap the custom editor tool action for use in an EditorToolbar with the EditorTool class.  The EditorTool class extends the Web ADF Tool and implements the IEditorToolbarItem interface.  These enhancements enable you to associate the custom tool with the id of the Map on which the tool will operate, determine whether snapping should be applied, define the feature types on which the tool can be used, and set the minimum number of selected features in the current editable layer to enable the tool.  All parameters are provided in the EditorTool constructor.  Additional properties on the editor tool are associated with standard custom tool implementation, such as client action, image bitmap display, and tool tips.  The custom editor tool action is associated with the editor tool via the ServerActionAssembly and ServerActionClass properties.   The ServerActionAssembly is the name of the assembly that contains the custom editor tool action class.  The ServerActionClass is the fully qualified name of the custom editor tool action class.  In the example below, a custom editor tool is created and added to a custom editor toolbar.  This example illustrates a custom EditorTask where image resources are embedded.  This code should be called during the CreateChildControls() method of the custom editor panel or when overriding CreateToolbars() in an Editor or EditExistingFeaturePanel subclass.
  
  [C#]

  EditorTool clip = new EditorTool("Clip", ParentEditor.MapID, false, ToolGeometry.Line
    ToolGeometry.Polygon, 1);
  clip.ClientAction = Constants.HTML_DRAG_RECTANGLE;
  clip.DefaultImage = this.Page.ClientScript.GetWebResourceUrl(typeof(CustomEditorTask),
    "CustomEditorTask_CSharp.images.clip.png");
  clip.SelectedImage = this.Page.ClientScript.GetWebResourceUrl(typeof(CustomEditorTask),
    "CustomEditorTask_CSharp.images.clip_ON.png");
  clip.HoverImage = this.Page.ClientScript.GetWebResourceUrl(typeof(CustomEditorTask),
    "CustomEditorTask_CSharp.images.clip_OVER.png");
  clip.ToolTip = "Clip feature(s)";
  clip.ServerActionAssembly = "CustomEditorTask_CSharp";
  clip.ServerActionClass = "CustomEditorTask_CSharp.ClipFeatures";
  
  newEditorToolbar.ToolbarItems.Add(clip);
  

• Custom Editor Command  
  
  A set of editor commands are included for use with the EditorTask.  The table below lists the class name and a description.
  
  

  EditorServerCommandAction class name	Description
  ClearSelection	Clears selected features in active edit layer.  Included with MainToolbar in the Editor.
  DeleteFeature	Delete the selected features in the active edit layer.  Included with GeometryToolbar1 in the EditExistingFeaturePanel.
  MergeFeature	Merge the selected features in the active edit layer. Included with GeometryToolbar1 in the EditExistingFeaturePanel.  Calls ITopologicalOperator3.Union()
  SetEditState	Handles commands associated with non-pooled and versioned edit operations.  The buttons to save, undo and redo edits included with MainToolbar in the Editor use this command class.
  ShowVertex	Show vertices of the selected feature in the active edit layer.  Included with MainToolbar in the Editor.

  
  When creating a custom command for the EditorTask, subclass the EditorServerCommandAction class and override the EditorServerAction method.   In general, the EditorServerCommandAction class wraps your custom command code for explicit use within the ArcObjects editing environment provided by the EditorTask.   The EditorServerCommandAction class is built on the base class EditorServerActionBase, which provides access to the current Editor, and the ArcObjects server context, IMapServer, IMap, IDataSet, and the IFeatureLayer and ArcGIS Server SOAP LayerDescription for the feature layer being edited.   In addition, a set of methods are available to modify pre and post editing operations, change error messages, refresh the Editor and display the EditorTask AJAX indicator.  
  
  The EditorServerCommandAction class provides a means for hooking into the pre and post command execute event framework in the EditorTask.  To use this event framework, override the EditorServerAction method to include the custom implementation code for your custom editor command.  This method will be called from within ServerAction in the EditorServerCommandAction class - after the PreCommandExecuteEvent and before the PostCommandExecuteEvent.  During EditorServerAction method implementation, call the StartEditOperation() method before the edit takes place (e.g. IFeature.Store()), call StopEditOperation() after the edit occurs, and call AbortEditOperation() is an exception is thrown during the edit process.  All edit operation methods will enable\disable a workspace for editing.  After command execution, Editor toolbars will be refreshed (enable\disable save edits button), edit status will be updated (display a notice if there are unsaved edits),  and the EditorTask AJAX indicator will be hidden.  The following code illustrates an abbreviated example of the implementation code associated with a custom editor command designed to convert selected polygons into polylines and store them in a predefined feature class. 
   
  [C#]

  namespace CustomEditorTask_CSharp
  {
      class PolygonToLine : EditorServerCommandAction
      {
          private List<int> features = new List<int>();
          public List<int> Features
          {
              get { return features; }
          }
  
          protected override void EditorServerAction()
          {
  	  . . .
  	  try
  	  {
  	    StartEditOperation();
  	    . . .
  	    agsCOMNewFeature = DestinationFeatureClass.CreateFeature();
  	    agsCOMNewFeature.Shape = agsCOMTopoOp3.Boundary;
  	    agsCOMNewFeature.Store();
  	    features.Add(agsCOMNewFeature.OID);
  	    . . .
  	    StopEditOperation();
  
  	  } catch (Exception e) {
  	    AbortEditOperation(e);
  	  }
  
  	  if (features.Count > 0)
  	  {
  	    Refresh(features, true);
  	  }
          }
      }
  }
  

  
  
  
  
  Wrap the custom editor command action for use in an EditorToolbar with the EditorCommand class.  The EditorCommand class extends the Web ADF Command by implementing the IEditorToolbarItem interface.   This interface enables you to define the feature types on which the command can be used, and the minimum number of selected features in the current editable layer to enable the command.   All parameters are provided in the EditorCommand constructor.  Additional properties on the editor tool are associated with standard custom command implementation, such as image bitmap display, and tool tips.  The custom editor command action is associated with the editor command via the ServerActionAssembly and ServerActionClass properties.   The ServerActionAssembly is the name of the assembly that contains the custom editor command action class.  The ServerActionClass is the fully qualified name of the custom editor command action class.  In the example below, a custom editor command is created and added to a custom editor toolbar.  This example illustrates a custom EditorTask where image resources are embedded.  This code should be called during the CreateChildControls() method of the custom editor panel or when overriding CreateToolbars() in an Editor or EditExistingFeaturePanel subclass.
  
  [C#]

  EditorCommand ptl = new EditorCommand("PolygonToLine", ToolGeometry.Polygon, 1);
  ptl.DefaultImage = this.Page.ClientScript.GetWebResourceUrl(typeof(CustomEditorTask),
    "CustomEditorTask_CSharp.images.polygon2line.png");
  ptl.SelectedImage = this.Page.ClientScript.GetWebResourceUrl(typeof(CustomEditorTask),
    "CustomEditorTask_CSharp.images.polygon2line_ON.png");
  ptl.HoverImage = this.Page.ClientScript.GetWebResourceUrl(typeof(CustomEditorTask),
    "CustomEditorTask_CSharp.images.polygon2line_OVER.png");
  ptl.ToolTip = "Convert polygon feature(s) to polylines";
  ptl.ServerActionAssembly = "CustomEditorTask_CSharp";
  ptl.ServerActionClass = "CustomEditorTask_CSharp.PolygonToLine";
  
  newEditorToolbar.ToolbarItems.Add(ptl);
  


Custom Editor Panels

The out-of-the-box EditorTask includes a set of prepackaged editor panels for use at runtime.  By default, there are two parent panels included with the Editor task: Editor and EditorSettingsPanel.  Both include a set of subpanels which contain logically grouped functionality.  The EditorTask also includes a set of components to support extending existing editor panels and creating new editor panels.   EditorPanel extends the Web ADF FloatingPanel, and provides access to the parent EditorTask, Editor, and the feature layer associated with the active edit layer.  TooledEditorPanel extends EditorPanel by defining a collection of toolbar items which can be populated by overriding the CreateToolbars() method.  Any subclass of TooledEditorPanel (e.g. EditExistingFeaturePanel) will trigger the ToolsCreated event on the EditorTask when CreateToolbars() returns. 

The technique for accessing and modifying panels depends on the custom EditorTask solution (option 1 or 2).   Note that the content of an editor panel will may contain an editor toolbar and toolbar items, discussed in the previous section.  

The Editor contains three editor panels by default.  Each panel is available via a property on the Editor and contains prepackaged functionality.  At a minimum, each panel is a type of EditorPanel.



Editor property	Description
NewFeatureCreator	Returns an instance of the CreateFeaturePanel.
ExistingFeatureEditor	Returns an instance of the EditExistingFeaturePanel. Subclasses TooledEditorPanel.
AttributesEditor	Returns an instance of the EditAttributesPanel.
EditorPanels	Returns a collection of editor panels contained by the Editor.


The EditorSettingsPanel contains two editor panels by default.   Some properties are provided on the EditorSettingsPanel to provide access to these subpanels. 
 

EditorSettingsPanel property	Description
SnappingPanel	Returns an instance of the SnappingPanel.
EditorPanels	Returns a collection of the editor panels contained by the EditorSettingsPanel.  Includes a reference to the SelectionPanel.


To add, remove or modify editor panels in the out-of-the-box EditorTask (option 1), handle the EditorPanelsCreated event to access the Editor panels collection; handle the SettingsPanelsCreated event to access the EditorSettingsPanel panels collection.   To add a panel, create a subclass of EditorPanel or TooledEditorPanel and add it to the collection exposed in the event argument.  To add controls to the custom panel, override the CreateChildControls() method.  To start with an existing editor panel (e.g. EditExistingEditorPanel), subclass the appropriate panel class and override the appropriate members.  For example, you can create a custom panel that subclasses the EditExistingEditorPanel class, override the CreateToolbars() method to add custom toolbar items, then add the custom panel to the Editor or EditorSettingsPanel.  Of course, you can also modify toolbars and toolbar items in the existing EditExistingEditorPanel via the ToolsCreated event.         

Here is a simple example of a custom EditorPanel. 

[C#]

public class MyPanel : EditorPanel
{
    public MyPanel(string title, EditorTask task, string ID) : base(title, task, ID) { }

    protected override void RenderContents(HtmlTextWriter writer)
    {
        writer.Write("This is my custom panel");
    }
}
                    

By adding this class to the App_Code folder of the EditorTask web application, the custom panel can be added to the out-of-the-box EditorTask with the following EditorPanelsCreated event handler code:

[C#]

protected void EditorTask1_EditorPanelsCreated(object sender, EditorPanelsCreatedEventArgs e)
{
	MyPanel panel = new MyPanel("My Custom Panel", EditorTask1, "myPanelID");
	e.EditorPanels.Insert(0, panel);
}
                    


At runtime, the custom panel will appear as follows. Note, in the code above the custom panel was inserted into the first position in the EditorPanel collection (index 0) so that the custom panel is displayed above the other standard EditorPanel panels.



Similarly, a custom panel can be added or can replace an existing panel when creating a custom EditorTask control (option 2).   In addition, you can also subclass the Editor and EditorSettingPanel class and override the CreateEditorPanels() method to define which panels are added.   The CreateEditorPanels() method is called in the CreateChildControls() method for each class.  A call to base.CreateEditorPanels() will return the default panels available in each container (Editor and EditorSettingsPanels).    You can either modify this collection or replace it.   If you replace an existing panel with a custom panel (e.g. replace the existing CreateFeaturePanel with a new panel to create features) override the appropriate method listed in the table below: 


Editor method	Description
CreateCreateFeaturePanel	Override to create a new instance of a create feature panel.  Returns a type of EditorPanel.
CreateEditExistingFeaturePanel	Override to create a new instance of an edit existing feature panel.  Returns a type of EditorPanel.
CreateEditAttributesPanel	Override to create a new instance of an edit attributes panel.  Returns a type of EditorPanel.
CreateEditorPanels	Override to modify the panels created for the Editor.  Returns a list of editor panels.


The Editor and EditorSettingsPanel share the technique for overriding CreateEditorPanels() to set the panels in either container.  However, the EditorSettingsPanel does not require you to override another method when replacing a SnappingPanel or SelectionPanel.  If replacing the existing SnappingPanel with a new panel that subclasses SnappingPanel (not just EditorPanel), override the SnappingPanel property.  The property should return a reference to the new panel created in CreateEditorPanels().


EditorSettingsPanel method	Description
CreateEditorPanels	Override to modify the panels created for the EditorSettingPanel.  Returns a list of editor panels.


The following code provides an example of overriding the CreateEditorPanels() method in a custom EditorSettingsPanel to define the editor panels it contains.

[C#]

public class CustomEditorSettingsPanel : EditorSettingsPanel
{
	protected override List<EditorPanel> CreateEditorPanels()
	{
	    List<EditorPanel> panels = new List<EditorPanel>();

	    CustomEditorTask customEditorTask = (CustomEditorTask)this.Task;
	    EditorPanel snappingPanel = null;
	    if (customEditorTask.UseMapUnitsForSnapping)
	    {
		snappingPanel = new CustomSnappingPanel(this.Task);
		snappingPanel.Visible = true;
	    }
	    else
	    {
		snappingPanel = new SnappingPanel(this.Task);
	    }
	    panels.Add(snappingPanel);

	    EditorPanel selectionPanel = new SelectionPanel(this.Task);
	    panels.Add(selectionPanel);

	    PolygonToLineLayerEditorPanel customPolygonToLinePanel =
		new PolygonToLineLayerEditorPanel("Polygon to Polyline Settings",
		this.Task, "P2PPanel");
	    panels.Add(customPolygonToLinePanel);

	    return panels;
	}
}			


To integrate a custom Editor or EditorSettingsPanel subclass the EditorTask and override the CreateEditor() or CreateEditorSettingsPanel() method to create and return an instance of the custom Editor or EditorSettingsPanel, respectively.  The following code provides a brief example of the implementation of a CreateEditor() method in a custom EditorTask.

[C#]

public class CustomEditorTask : ESRI.ArcGIS.ADF.ArcGISServer.Editor.EditorTask
{
	protected override ESRI.ArcGIS.ADF.ArcGISServer.Editor.Editor CreateEditor()
	{
	    return new CustomEditor(this);
	}
}