This document is archived and information here might be outdated.  Recommended version.


Using feature templates (ArcObjects .NET 10.5 SDK)

Using feature templates


Summary
This topic describes feature templates and their use to create features in the editing environment, feature template management, and how they are used in the process of creating features.

In this topic


About feature templates

Feature templates are a central concept in the editing environment in ArcGIS. Creating features using the editor relies on the use of feature templates.
Feature templates provide an easy way to simplify and streamline the creation of features using the editor. Because a number of properties required to set up the editing environment and attribute the feature are predefined, the user can easily select a template, and a number of steps are performed automatically, making the user's task much simpler.
Every feature template is associated with a FeatureLayer; they are stored in the layer as a layer extension. When a layer is persisted (that is, as a layer file or in a map document), the feature templates are stored as part of the layer's definition.
Templates are used to create all types of features, including simple features (such as point, line, and so on) as well as geometric network features, annotation features, and dimension features.
Feature templates define the following required and optional properties:
  • Required properties
    • Name—The name of the feature template that displays.
    • Target layer—Defines the layer (and feature class) where new features will be stored.
  • Optional properties
    • Default attribute values—Defines field values to be applied to each new feature created using this feature template.
    • Description—User-defined string that is used to provide additional information, such as appropriate use.
    • Tags—User-defined and system-generated keywords to describe the template. Tags are delimited by a semicolon.
    • Tool—Default tool used to create features based on this feature template.
One property that is not stored as part of the feature template is its symbology. The feature template holds a reference to the layer and knows how to draw the created feature using the feature template based on the feature template's default values. Because any change to the layer's renderer also affects the feature template's symbology, you do not need to keep the layer symbology and feature templates synchronized. 
A feature does not persist its relationship to the template that created it. Once the feature is created, any relationship to the feature template is lost.
Feature templates in the editor are shown in the following two places:
  • Create Features window
  • Control on several editing dialog boxes associated with commands, such as Copy Parallel that create features

    See the following screen shot:


Map authors create and manage feature templates with the Organize Feature Templates dialog box. This dialog box can be accessed via the Organize Templates command in the Create Features window while editing, or any time via the Edit Features menu item on the layer context menu.

Each template represents a unique rendered value within the feature layer. The map author can modify the default attribute values and default construction tool used to create the new type of feature. For more information on working with templates in ArcMap, see the Creating features with templates section in What is editing?.
When the user selects a feature template, the editor's current task is set to Create New Feature, Create 2-point line features, or AutoComplete Polygon, then the template's default construction tool is activated.

Creating feature templates

By default, when an edit session is started on a workspace, and the editable layers in that workspace do not have any feature templates defined, the editor creates templates for each layer and unique renderer value automatically. This does not happen if any associated feature templates exist.
Within the application programming interface (API), templates are created using the IEditTemplate and IEditTemplateFactory interfaces in the esriCarto assembly, and managed through the IEditor3 interface. The current or selected template is obtained from the IEditor3.CurrentTemplate, which returns an IEditTemplate.
New templates are created via the IEditTemplateFactory interface for a given layer within an edit session. The following code example shows how to create a feature template called Building for the selected layer in the map. The code example assumes you have a reference to the application.
[C#]
//Create a single template for the selected layer.
ILayer editLayer=m_doc.SelectedLayer;
IEditTemplateFactory editTemplateFact=new EditTemplateFactoryClass();
IEditTemplate newEditTemplate=editTemplateFact.Create("Building", editLayer);

//Add the template.
IArray templateArray=new ArrayClass();
templateArray.Add(newEditTemplate);
m_editor.AddTemplates(templateArray);
[VB.NET]
'Create a single template for the selected layer.
Dim pLayer As ILayer=m_doc.SelectedLayer
Dim editTemplateFact As IEditTemplateFactory=New EditTemplateFactory
Dim newEditTemplate As IEditTemplate=editTemplateFact.Create("Building", pLayer)

'Add the template.
Dim templateArray As IArray=New Array
templateArray.Add(newEditTemplate)
m_editor.AddTemplates(templateArray)
After you've created the template, you can alter the attributes for the template via methods on the IEditTemplate interface. Use the IEditTemplate.SetDefaultValue method to set the default value for each field. To create templates for all possible values based on the layer's renderer (as the Organize Feature Templates dialog box does), create each template separately, then modify the field value within the template on which the layer is being rendered.
Templates are added to the Create Features window via the IEditor3.AddTemplates method, which takes an IArray of feature templates.

Accessing feature templates

Feature templates are stored as part of the layer in a layer extension. To examine templates for a layer outside an edit session, use IEditTemplateManager.
The following code example shows how to access the EditTemplateManager for a given layer:
[C#]
public void GetEditTemplateManager(ESRI.ArcGIS.Carto.ILayer layer)
{
    ILayerExtensions layerExtensions;
    IEditTemplateManager editTemplateMgr;
    layerExtensions=layer as ILayerExtensions;

    //Find the EditTemplateManager extension.
    for (int j=0; j < layerExtensions.ExtensionCount; j++)
    {
        object extension=layerExtensions.get_Extension(j);

        if (extension is IEditTemplateManager)
        {
            editTemplateMgr=extension as IEditTemplateManager;
            //Use EditTemplateManager to get information about templates.
        }
    }
}
[VB.NET]
Private Sub GetEditTemplateManager(ByVal layer)
    Dim layerExtensions As ILayerExtensions
    Dim editTemplateMgr As IEditTemplateManager
    layerExtensions=layer
    'Find the EditTemplateManager extension.
    For j As Integer=0 To layerExtensions.ExtensionCount - 1
        Dim extension As Object=layerExtensions.get_Extension(j)
        If TypeOf extension Is IEditTemplateManager Then
            editTemplateMgr=extension
            Exit For
        End If
    Next
    'Use EditTemplateManager to get information about templates.
End Sub

Updating feature templates

Once you have a reference to the EditTemplateManager, you can interrogate each of the feature templates stored with that layer and subsequently view or update its properties. In many cases, developers will want to update the default value for a field or fields so they are populated automatically when the feature is created, and default values are applied from the template.
The following code example shows how to set a default value for a given field on a template. Updating other properties, such as the name of the feature template, tags, and so on, can also be performed in the same manner:
[C#]
IEditTemplate editTemplate=editTemplateMgr.get_EditTemplate(0);
editTemplate.SetDefaultValue("Name", "Venice", true);
[VB.NET]
Dim editTemplate As IEditTemplate=editTemplateMgr.get_EditTemplate(0)
editTemplate.SetDefaultValue("Name", "Venice", True)

Removing templates

Templates can be removed from the Create Features window via the IEditor3.RemoveTemplate method passing an IEditTemplate reference. You can also remove all templates from the map or an individual layer using the IEditor3_RemoveAllTemplatesInMap and IEditor3.RemoveAllTemplatesInLayer methods.
To remove templates of a certain criteria, such as those of a certain geometry type, iterate through the template list (IEditor3.TemplateCount and IEditor3.Template), inspect the template via IEditTemplate properties, then remove the template if it met the criteria.

Working with templates

Users will typically select a template to create a feature. When they do, the edit task is set to Create New Feature and the default tool is activated for the selected template. You can use the selected template with your customizations to set a target layer for some functionality or get access to the default values for the current template. Templates allow you to populate the values of features with a few lines of code.
The following code example from a custom edit tool uses the information from the current template to create a point feature in a layer and sets the default attribute values for all fields. The code example assumes that you have a currently selected template that is associated with a point layer.
[C#]
public void m_editEvents_OnSketchFinished()
{
    //Create a point at the end of the sketch for the current point template.
    m_editor.StartOperation();
    IPoint point=m_edSketch.LastPoint;
    IEditTemplate editTemplate=m_editor.CurrentTemplate;

    IFeatureLayer featLayer=editTemplate.Layer as IFeatureLayer;
    IFeatureClass featClass=featLayer.FeatureClass;
    IFeature newFeature=featClass.CreateFeature();
    newFeature.Shape=point;

    //Apply default values as stored in the template properties.
    editTemplate.SetDefaultValues(newFeature);
    newFeature.Store();
    m_editor.StopOperation("Create Point");

    //Invalidate the area around the new feature.
    m_editor.Display.Invalidate(newFeature.Extent, true, (short)
        esriScreenCache.esriAllScreenCaches);
}
[VB.NET]
Public Sub m_editEvents_OnSketchFinished()
    'Create a point at the end of the sketch for the current point template.
    m_editor.StartOperation()
    Dim point As IPoint=m_edSketch.LastPoint
    Dim editTemplate As IEditTemplate=m_editor.CurrentTemplate
    
    Dim featLayer As IFeatureLayer=editTemplate.Layer
    Dim featClass As IFeatureClass=featLayer.FeatureClass
    Dim newFeature As IFeature=featClass.CreateFeature()
    newFeature.Shape=point
    
    'Apply default values as stored in the template properties.
    editTemplate.SetDefaultValues(newFeature)
    newFeature.Store()
    m_editor.StopOperation("Create Point")
    
    'Invalidate the area around the new feature.
    m_editor.Display.Invalidate(newFeature.Extent, True, CShort(esriScreenCache.esriAllScreenCaches))
End Sub






To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS Desktop Basic ArcGIS Desktop Basic
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced