In this post, Rex Hansen describes how to customize the .NET Web ADF EditorTask control and provides a downloadable sample.
While the EditorTask includes a comprehensive set of out-of-the-box capabilities, many Web editing solutions require customizing the behavior of the EditorTask to satisfy user specific requirements. The EditorTask offers two options for developing a custom solution:
- Using the out-of-the-box EditorTask, add custom functionality by handling EditorTask events in a page.
- 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 Save button will 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, packaged in 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. 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 allow the addition and/or removal of panels.
The EditorTask was explicitly designed to support customization in the following distinct, but related categories:
- EditorTask events
- Attribute Filtering
- Custom Editor Tools
- 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 are demonstrated in the example provided, within the context of each category.
Option 1 uses an out-of-the-box EditorTask control and EditorTask events within the context of the pagecontrol 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). The diagram below highlights where the implementation of each customization category may occur when extending the EditorTask.
What’s in the sample
To get the sample, download one of the following based on your preference for C# or VB.NET:
Two projects are packaged with the sample:
A class library project (CustomEditorTask_<language>) that contains the classes and content needed to create a custom EditorTask control. Note the following customizations:
- On initial load of the custom EditorTask, attributes for the “Tentative Assessed Parcels”, “Address Points” and “Water Bodies” layers are filtered for display.
- On post tool execute, if a feature was created or modified in the “Tentative Assessed Parcels” layer, the time of the edit is written to respective fields in the feature class.
- The EditExistingFeaturePanel has been replaced by a custom Editor panel. The custom panel subclasses EditExistingFeaturePanel and adds two custom Editor tools, clip features and convert polygon to polyline.
- A set of custom properties on the EditorTask define if map units should be used for snapping. If true, a custom EditorSettingsPanel replaces the existing default panel. The custom panel also contains a custom SnappingPanel which contains the logic necessary to snap using map units (pixel tolerance changes with map scale).
A Web project (CustomEditorTaskWebApp_<language>) that contains two pages and a set of custom components (Editor tools and panels) in the App_Code folder. One page includes a reference to the custom EditorTask control created in the aforementioned project. The other page contains an out-of-the-box Editor task which is customized by handling events on the EditorTask. Both pages handle the release of server context for non-pooled services via a callback when the browser is closed. Note the following customizations to the out-of-the-box EditorTask:
- On initial load of the page, attributes for the “Tentative Assessed Parcels”, “Address Points” and “Water Bodies” layers are filtered for display and applied to the EditorTask.
- A custom CreateFeaturePanel is added to the Editor. It contains a custom tool that references the prepackaged CreateFeature EditorToolServerAction.
- A custom clip Editor tool is added to the existing GeometryToolbar1 in the EditExistingFeaturePanel.
- A custom Editor toolbar and custom Editor command is added to the EditExistingFeaturePanel.
- On pre attribute update, if a field named “UPDATEDBY” exists in the active edit layer and an authenticated user has been defined, add the username as a field value.
- On post attribute update, if update was not successful, return the exception message in an alert box.
- On pre command execute, cancel actions that delete features in the “Address Points” layer.
How to set up the sample
This section explains how to set up the sample after you have downloaded the two projects mentioned above. Before you begin, unzip the Common_CustomEditorTask_<language> zip file into a folder accessible from IIS (e.g. c:inetpubwwwroot).
Set up access to the geodatabase
You must have access to Microsoft SQL Server Express which has been configured for use with ArcSDE Workgroup geodatabases to use the data packaged with the sample. If you use your own data, you will need to change some portions of the sample code to function.
- Assuming you have access to SQL Server Express configured for use with ArcSDE Workgroup geodatabases, open ArcCatalog; under Database Servers click Add Database Server and connect to SQL Server Express.
- Right-click on the SQL Server Express instance and select Permissions. Add the ArcGIS Server container account.
- Right-click the SQL Server Express instance and select Attach. Navigate to the EditParcels.mdf included with the sample (e.g. c:inetpubwwwrootCommon_ CustomEditorTask _CSharpdataEditParcels.mdf). The EditParcels geodatabase should be added to the geodatabase list for the SQL Server Express instance in ArcCatalog.
- Right-click on the EditParcels geodatabase and select Administration>Permissions. Grant the ArcGIS Server container account readwrite privileges.
Configure the map document and create the map service
- Open the EditParcelsDemo.mxd in ArcMap. Note that the data source for every layer is invalid, thus a red exclamation point is displayed next to each layer name. Click (single left mouse button click) on the red exclamation point next to the “Address Points” layer to display the Set Data Source dialog.
- Navigate to the SQL Server Express instance on which the EditParcels geodatabase is available. Select the “EditParcels.DBO.AddressPoints” feature class and select OK. Data sources for all layers in the map document should be repaired. Save the map document. ArcMap should appear as follows.
Open ArcCatalog and add a new map service with the following properties:
Map document: <path to EditParcelsDemo.mxd>
Pooling: Not Pooled, Min instances: 0, Max instances 6
When finished, start the service.
Configure the EditorTask projects
- Open the IIS Manager from Control Panel > Administrative Tools > Internet Information Services (IIS) Manager or Internet Information Services
- In the console tree view on the left, navigate to Local Computer > Web Sites > Default Web Site.
- Open the Common_ CustomEditorTask _<language> folder, right-click the CustomEditorTaskWebApp_<language> folder and click Properties.
- On the Directory tab, click the Create button in the Application Settings section of this panel. Click OK to dismiss the Properties dialog.
- Launch Microsoft Visual Studio 2005 and open the Common_ CustomEditorTask _<language> solution located where you unzipped the file in step 1. (e.g. c:inetpubwwwrootCommon_ CustomEditorTask _CSharpCommon_CustomEditorTask _CSharp.sln).
- In the Solution Explorer, right-click the CustomEditorTaskWebApp _<language> project and select ‘Set as StartUp Project’. Also, right-click CustomEditorTaskPage.aspx and select ‘Set As Start Page’.
- If necessary, set an impersonation identity for the Web application. Right-click on the Web project and select “Add ArcGIS Identity”. Enter the credentials of a user account which has been added to the agsadmin or agsusers group on the SOM (server object manager) where the EditParcelsDemo map service is running.
- Open the CustomEditorTaskPage.aspx in design view and define the connection properties for the single ArcGIS Server Local map resource item in the MapResourceManager.
- Also in design-view, set CustomEditorTask1 control properties to define the map and resource, editable layers (select all) and editable versions (select all).
- Open the StandardEditorTaskPage.aspx and modify the MapResourceManager and EditorTask1 using the same properties defined in the CustomEditorTaskPage.aspx.
- Build the solution. View both Web pages in a browser and use the EditorTask at runtime. The following screenshot shows the CustomEditorTaskPage.aspx at runtime: