Working with the EditorTask control

In this topic

• Customizing the EditorTask control
• Panel structure and naming
• Customization categories
• EditorTask events
• Attribute filtering
• Custom editor toolbars and toolbar items
• Custom editor panels

Customizing the EditorTask control

• Option 1—Adds custom functionality by handling EditorTask events on a page. This option provides convenient access to standard EditorTask events in a Web application.
• Option 2—Creates a custom Web control by subclassing the EditorTask and its child controls. This option is more complex and provides comprehensive access to the implementation details (including events) of the EditorTask and its subcomponents. It also enables you to package a Web Application Developer Framework (ADF) editing solution as a redistributable custom EditorTask control. 

• Editor—Composite control that contains a VersionIDPanel or a set of editor panels and other controls to edit feature layers. 
• EditorSettingsPanel—Type of EditorPanel that contains a SnappingPanel and SelectionPanel. 

Panel structure and naming

If an editable layer is versioned and more than one version is available for editing, the VersionIDPanel shows in the Editor when the EditorTask is initialized at runtime. See the following screen shot:

• When editing a non-versioned feature layer in a pooled service, the main toolbar does not contain an Undo, Redo, or Save button. 
• When editing non-versioned data in a non-pooled service, the Undo and Redo buttons are not available. 

• CreateFeaturePanel—Contains one or more tools to create a feature depending on the active edit layer feature type (also has a toolbar that cannot be customized). 
• EditExistingFeaturesPanel—Contains tools and commands to modify existing features and has the following toolbars:
• GeometryToolbar1—Includes items to modify entire features (can be customized).
• GeometryToolbar2—Includes items to manipulate feature vertices (can be customized).   
• EditAttributesPanel—Lists the attributes of the current set of selected features. Since only one feature's attributes can be visible, paging is enabled when more than one feature is selected. The visibility and edit ability of attributes can be modified via attribute filtering. Attribute labels and text boxes are generated internally by the EditAttributesPanel and are not available for explicit customization.
  
  See the following screen shot that shows these Editor panels and associated toolbars:
  
  

• EditorSettingsPanel—The EditorTask also contains an EditorSettingsPanel that can be initialized via the Editor at runtime and compliments actions initiated by Editor panels. The EditorSettingsPanel contains the following panels:
• SnappingPanel—Provides the ability to change snapping rules and SnapTips display at run time. 
• SelectionPanel—Provides the ability to modify selection behavior when using the select tool on the Editor's main toolbar.  
  
  The SnappingPanel and SelectionPanel are not customizable; however, you can add or remove panels from the EditorSettingsPanel.
  
  See the following screen shot that shows these Editor panels: 
  

Customization categories

• EditorTask events
• Attribute filtering
• Custom editor toolbars and toolbar items 
• Custom editor panels

Option 1 uses an out-of-the-box EditorTask control and EditorTask events within the context of the page's and control's life cycle to implement custom capabilities in each category. You can add event handlers during the page's or EditorTask control's life cycle events (for example, init and load).

The following illustration highlights where these categories can be leveraged with option 1:

 

Instead of working with the event handler, EditorTask and Editor events are overridden in their respective subclass. 

The following illustration highlights where the implementation of each customization category can occur when extending the EditorTask:

 

EditorTask events

• EditorPanelsCreated—Triggered after the panels in the Editor are created during the CreateChildControls() method. The created panels are CreateFeaturePanel, EditExistingFeaturePanel, and EditAttributesPanel. The event argument (EditorPanelsCreatedEventArgs) references a collection of panels. For more information, see the Custom editor panels section in this topic.
• SettingsPanelsCreated—Triggered after the panels in the EditorSettingsPanel are created during the CreateChildControls() method. The created panels are SnappingPanel and SelectionPanel. The event argument (EditorPanelsCreatedEventArgs) references a collection of panels and can be used to add, remove, or modify panels. For more information, see the Custom editor panels section in this topic.
• ToolsCreated—Triggered twice per request, when the toolbar in the Editor control is created and when the toolbars in the EditExistingFeaturePanel are created. The Editor control contains one toolbar with the MainToolbar ID. The EditExistingFeaturePanel contains GeometryToolbar1 and GeometryToolbar2. The CreateFeaturePanel contains a toolbar, but it cannot be customized. Handle this event to remove and 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. For more information, see the Custom editor toolbars and toolbar items section in this topic.
• SetVersion—Triggered via a postback or 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) returns the selected version string.
• LayerChanged—Unique event because the event handler is exposed on the Editor, not the EditorTask. LayerChanged can be triggered via a postback or callback initiated (by two actions in an Editor) when a geodatabase version is selected in the VersionIDPanel and when a layer is selected on 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 modified EditorTask behavior, or prepare the feature layer for editing. The event argument (IFeatureLayer) provides access to the ArcObjects feature layer and feature class. 
  
  The following illustration shows the event type, the EditorTask component that triggers the event, and when it is triggered (for example, which method in the component). The CreateChildControls() method for all components is called between the control load, page pre-render upon the initial request, and between page init and page load during every postback and callback. 
  
  

• PreAttributeEdit—Triggered when the value in a text box on the EditAttributesPanel is changed, and the text box loses focus. A callback to the EditAttributesPanel calls the SaveEdit() method (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() method. Handle this event to modify the provided attribute value or update other attributes during the same operation. The event argument (PreAttributeEditEventArgs) provides access to the IFeatureLayer, IFeature, and IField interfaces 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—Triggered when the value in a text box on the EditAttributesPanel is changed and the text box 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() method. Handle this event to modify information shown to the user or update other related server-side content. The event argument (PostAttributeEditEventArgs) provides access to the IFeatureLayer, IFeature, IField interfaces and the new value used in the edit operation. You can also verify 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.
  
  See the following illustration that shows the PreAttributeEdit and PostAttributeEdit events:
  
  

• PreCommandExecute—Triggered when clicking a toolbar button 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 (can be an EditorToolbar) calls the EditorServerAction() method in the custom command action class. 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 useful if you do not have access to the command source code or need to initiate the same set of actions before any group of commands execute. The event argument (PreCommandExecuteEventArgs) provides access to the ServerAction class (EditorServerCommandAction class), which references several useful properties. The IMap, IMapServer, and server context of the map service associated with the command action are available. 
  
  The ArcObjects IDataset and Simple Object Access Protocol (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, 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—Triggered when clicking a button on a toolbar in the EditorTask. 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 several useful properties. This event argument exposes the same properties as PreCommandExecuteEventArgs minus the Cancel option.
  
  See the following illustration that shows the PreCommandExecute and PostCommandExecute events:
  
  
  
• PreToolExecute—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. 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 several 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 (same Map control that generates 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 the active edit layer name, 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—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. 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 several useful properties. This event argument exposes the same properties as the PreToolExecuteEventArgs minus the Cancel option.
  
  See the following illustration that shows the PreToolExecute and PostToolExecute events:
  
  

Attribute filtering

• Specify how attributes display by default.
• Define how specific fields show using the Add method.

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);
}

Custom editor toolbars and toolbar items

• The Editor contains a toolbar (MainToolbar) to manage selecting features and saving edits. 
• The EditExistingFeaturePanel contains GeometryToolbar1 and GeometryToolbar2 toolbars. GeometryToolbar1 contains toolbar items to manage complete feature edits. GeometryToolbar2 contains toolbar items to manage feature vertex edits.

• 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 the following ways: 
• Sets the toolbar group for all EditorToolbars to the same value, EditorToolbarGroup. 
• Enables and disables toolbar items depending on the feature type and number of features selected in the active edit layer.  
  

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 following table shows the class name and description. The class name is usually different than the editor tool name. For example, the EditExistingFeaturePanel included with the EditorTask contains an EditorTool (CopyPointFeature) whose ServerActionClass references the CopyFeature class.

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 to use in an EditorToolbar with the EditorTool class. The EditorTool class extends the Web ADF tool and implements the IEditorToolbarItem interface. See the following illustration:



These enhancements enable you to associate the custom tool with the ID of the Map on which the tool operates, 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 ToolTips. 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. 

The following code example shows a custom editor tool created and added to a custom editor toolbar. This code example shows a custom EditorTask where image resources are embedded. Call this code during the CreateChildControls() method of the custom editor panel or when overriding CreateToolbars() in an Editor, or EditExistingFeaturePanel subclass.

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 to use with the EditorTask. The following table shows the class name and description:
  

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 to use in an EditorToolbar with the EditorCommand class. The EditorCommand class extends the Web ADF command by implementing the IEditorToolbarItem interface. See the following illustration:



The IEditorToolbarItem 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 ToolTips. 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.  

The following code example shows a custom editor command created and added to a custom editor toolbar. The code example shows a custom EditorTask where image resources are embedded. Call this code during the CreateChildControls() method of the custom editor panel or when overriding CreateToolbars() in an Editor, or EditExistingFeaturePanel subclass.

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

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");
    }
}

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

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;
    }
}

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

See Also: