In this topic
- How do I add editing functionality to my application?
- How does editing work?
- Designing your editing experience
The APIs include components (or widgets) that help you add editing functionality to your applications. You can do some design work in both your map and your Web application to simplify the end user experience when editing. For example, you might predefine a set of feature templates, introduced at 10.0, to make it easier for users to add certain types of common features. You might also limit the attributes that can be added, and add some available attribute options in a drop down list to facilitate accurate, uniform data entry. As the designer of a Web editing application, you have complete control over how simple or complex of an editing experience you expose to your users.
Web editing requires some initial setup of a feature service, which exposes information about a layer's feature geometries and attributes. Also, geometry services can be used to accomplish some Web editing tasks. In order to use the main Editor component, for example, you must have a running geometry service.
What can I do with editing in the ArcGIS Web APIs?
The ArcGIS Web APIs provide simple feature editing. The features must come from an ArcSDE geodatabase. This geodatabase can be licensed for either workgroup or enterprise use and does not have to be versioned.
When editing data with the Web APIs, you can add, delete, cut (split), merge (union), and reshape features. You can also edit feature attributes. If you attempt to modify the same feature at the same time as someone else, the last edits to be made are the ones committed to the database.
For certain Web editing workflows, it is a good idea to have an analyst using ArcGIS for Desktop periodically review the edits to verify data integrity. Although the editing components can perform some data validation, other tasks such as validating topologies cannot be performed over the Web.
How do I add editing functionality to my application?
The ArcGIS API for Flex provides multiple components to make it easier for you to add editing functionality to your Web applications.
If you want to get started quickly, or if you just want to use the default editing interface included with the API, use the Editor component. The Editor component combines the functionality of the other components to provide everything that you need for editing a layer. You can choose the number and types of tools that are available on the component.
The Editor component saves your edits immediately after they are made, for example, as soon as you finish drawing a polygon. If you decide not to use the Editor component, you must determine for yourself when and how often you want to apply edits.
If you don't use the Editor component, you need to code your own editing experience. However, you can still take advantage of the DrawTool, EditTool, TemplatePicker, AttributeInspector and AttachmentInspector to help you - as shown in the Edit without Editor sample.
The TemplatePicker component displays a set of pre-configured feature choices that the user can create. The Template Picker is a great way to expose pre-configured feature types for easy editing and quality control. The symbols in the Template Picker come directly from the editing templates that you defined in the map document of your feature service.
A Template Picker is included in the Editor component. The Template Picker can also be used on its own as a simple legend for your map.
When you make attributes available for editing on the Web, you need to provide an interface for users to edit the attributes, and you must ensure that the data they enter is valid. The Attribute Inspector component can help you with both these tasks.
The Attribute Inspector reads the attribute fields available through your feature layer and provides a user interface for easily updating those fields. It also validates data entered in the fields, ensuring that the input matches the expected data type. For example, if a coded value domain is applied to a field, the permitted values appear in a drop down list, restricting the possibility of other values being entered. If a field requires a date value, a calendar appears, helping the user to supply a valid date.
The Attribute Inspector exposes the available attributes on the layer for editing. Use the outFields property on the FeatureLayer to set the available attributes.
An Attribute Inspector is included in the Editor component.
In some situations, you may want to associate a downloadable file with a feature. For example, you might want users to be able to click a feature representing a piece of real estate and see a link to a PDF file of the title deed. In the ArcGIS Web APIs, an associated downloadable file like this is known as a feature attachment. See the FAQ on How do I upload large attachments.
The AttachmentInspector component helps users upload and view the list of feature attachments. The Attachment Editor includes a list of current attachments (with Remove buttons), as well as a Browse button that can be used to upload more attachments. The Attachment Editor works well inside an InfoWindow, but can be placed elsewhere on the page.
In order to use feature attachments, attachments must be enabled on the source feature class. You can enable attachments for a feature class in ArcCatalog or the Catalog window in ArcMap.
Many times while viewing features, either in the form of a pop-up dialog or even a table, you may wish to view, or possibly edit, any related features or records associated with that feature. The RelationshipInspector component was added with version 3.1 and allows end-users to view related records for features as well as add or delete related records.
You can think of this component as a 'building block' used in other components. For example, you could use this in both the Pop-up window and/or an AttributeTable component. This component's functionality and use is very similar to the AttachmentInspector component. For example, you can view and add attachments on a given feature. Many times you can view the associated attachment inside a pop-up window. The same premise can be applied to relates as well.
Adding of related records using the RelationshipInspector component is only supported when using ArcGIS 10.1 or later. Also, the related "table" is an actual table and not a layer. Also adding of related records is not supported if the cardinality is defined as 1-to-1 and there is already a related record for a given feature.
In order for your ArcGIS service to have relationships, your geodatabase needs to have relationship classes or you need to configure relates in the map document. For more information about configuring your service to support related records, read the ArcGIS Help.
How does editing work?
Editing with the ArcGIS Web APIs works through the feature service, a new type of service available with ArcGIS 10.0. Editing workflows can also take advantage of the geometry service.
The role of the feature service
Web editing requires a feature service to provide the symbology and feature geometry of your data. The feature service is just a map service with the Feature Access capability enabled. This capability allows the map service to expose feature geometries and their symbols in a way that is easy for Web applications to use and update.
Before you build a Web editing application, you need to do some work to create a feature service exposing the layers that you want to be edited. This involves setting up a map document and, optionally, defining some templates for editing. Templates allow you to pre-configure the symbology and attributes for some commonly-used feature types. For example, to prepare for editing roads, you might configure templates for "Controlled Access Freeway", "Other Divided Highway", "State Highway", and "Local Road". Templates are optional, but they make it easy for the end user of the application to create common features.
Once your map is finished, you need to publish it to ArcGIS Server with the Feature Access capability enabled. This creates REST URLs, or endpoints, to both a map service and a feature service. You will use these URLs to reference the services in your application.
Feature services are accessible in the Web APIs through a new type of layer called a feature layer. Feature layers can do a variety of things and can reference a layer in either a map service or a feature service; however, when you use a feature layer for editing purposesyou need to reference a layer in a feature service.
When you perform editing, your Web application tells the feature layer which attributes have changed and, if applicable, how the geometry changed. The feature layer also displays the updated features after editing. You can call the applyEdits() method on the feature layer to apply the edits, which then commits them to the database.
The role of the geometry service
The ArcGIS Server geometry service helps perform common editing operations such as creating, cutting, and reshaping geographic features. Before you use the Editor component, you need to create a geometry service on your ArcGIS Server. Then when you create the Editor component, you must provide the URL to the geometry service. The component uses the service behind the scenes, and you won't have to call methods on the geometry service yourself unless you decide not to use the component.
If you decide not to use the Editor component, you can still use the geometry service to help you code your own editing tools. The geometry service can also help you validate data. For example, you can use the geometry service to perform checks on edits, such as "no edit may fall outside this box", or "a polygon boundary may not cross itself". The Editor component actually calls the simplify() method on the geometry service before it commits a geometry to your database. Although ArcGIS topology validation is not available through the Editor component or editing-related classes, the geometry service may help you achieve a similar result through these types of data integrity checks.
The EditTool helps you move graphics or their individual vertices. This is helpful in scenarios where you are not using the Editor component and you need to write your own editing logic, especially the client display behavior.
The DrawTool helps you create new features by drawing them. It is commonly used in combination with the TemplatePicker to create new features based on the selected feature template.
Designing your editing experience
When you build a Web editing application, it is important to think about who will use the application and what they will need to do. You should provide your users no more and no less than the tools they need. In most situations you can design an appropriate editing experience for your users through a combination of the editing components included with the API. Keep in mind that although the API includes a comprehensive Editor component to help you get started, this particular component may not be the best fit for your scenario.
In some ways, the editing experience with the API has already been simplified for you. The components include no buttons for starting and stopping edit sessions, or for saving edits. You can provide these functions, but they're not necessary for most applications.
Consider the following approaches for designing a Web editing application. Each approach has its own merits and types applications for which it is most appropriate.
In this type of application, field analysts need to sketch simple events on the map, such as bird sightings. The geographic precision of the edits is not as important as the event's attributes and the fact that the event happened. In this type of an application, you can use a Template Picker to limit the types of items users can sketch. The Attribute Inspector is also useful, either in a side panel or in an info window that appears when the feature is clicked. Options for splitting and merging features, adding a point at an X/Y location, snapping, or uploading feature attachments may clutter the application and should be avoided unless absolutely needed.
View a sample that shows how to build a feature sketching application.
Some editing applications include a mapping component, but don't require any changing of geographic features. For example, you might want to create a Web application allowing any office employee to edit the attributes of a parcel feature in your database. You want to prevent them from editing the geometry, leaving that task to your GIS analysts. In this scenario, you can include a map in your application, but expose editing only through the Attribute Inspector. A simple map click on a parcel displays the attributes to be edited. You don't need to include any buttons or components for creating, deleting, or reshaping features.
View a sample that shows how to build an attribute editing application.
Citizen participation, or geo-wiki
In this type of application, citizens can be the editors and report problems to a government organization by placing points on the map and including ancillary information such as photographs or a brief description.
Users of this type of application do not even know that they are editing GIS data. They are only allowed to add point features to the database, using a carefully selected set of incident types that you predefined in a Template Picker. Attachments are allowed through the Attachment Inspector component so that citizens can upload images of the incident. Attribute editing may be allowed to a very limited degree so that citizens can describe the incidents.
In this type of application, you may have to code some security checks to ensure that users can only edit or delete their own incidents. You may also include logic to periodically clean out the database, or allow a subset of authenticated users to close or delete incidents.
View a sample that shows how to build a citizen participation application.
To get a good idea of how editing works. The ArcGIS Viewer for Flex's edit widget's source code provides a good example of how to implement and work with this functionality. You can download and access this at github. If you downloaded the entire application, refer to the files located in the src/widgets/edit folder.