Summary
Provides the ability to insert a layer at a specific location within a data frame or within a group layer in a map document (.mxd).
Discussion
InsertLayer is a more precise way of positioning a layer into a data frame or a group layer because a reference layer is used to specify the exact location. The layer is either added before or after the reference layer.
If the reference layer references a layer at the root level of a data frame, the inserted layer will be added to the root level of the data frame. If the reference layer references a layer within a group layer, the inserted layer will be added into the group. Because a reference layer is a required parameter, it is not possible to use InsertLayer to add a layer into an empty data frame or empty group layer. The AddLayer or AddLayerToGroup functions do allow you to add a layer into an empty data frame or group layer, respectively.
The layer that is inserted must reference an already existing layer (keep in mind that a layer can be a group layer as well). The source can either come from a layer file on disk, from within the same map document and data frame, the same map document but different data frame, or even from a completely separate map document.
The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbol(s) in the TOC. This setting is built into the layer. If a layer is collasped, saved to a layer file, and then added to a map document, the layer will be collasped in the new map document when added via InsertLayer.
Syntax
InsertLayer (data_frame, reference_layer, insert_layer, {insert_position})| Parameter | Explanation | Data Type |
data_frame | A reference to a DataFrame object into which the new layer will be inserted. | DataFrame |
reference_layer | A Layer object representing an existing layer that determines the location where the new layer will be inserted. | Layer |
insert_layer | A reference to a Layer object representing the layer to be inserted. | Layer |
insert_position | A constant that determines the placement of the added layer relative to the reference layer.
(The default value is BEFORE) | String |
Code sample
The follwing script will insert a new layer from a layer (.lyr) file on disk and place it before a layer called Lakes which is in a data frame called County Maps.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "County Maps")[0]
refLayer = arcpy.mapping.ListLayers(mxd, "Lakes", df)[0]
insertLayer = arcpy.mapping.Layer(r"C:\Project\Data\Rivers.lyr")
arcpy.mapping.InsertLayer(df, refLayer, insertLayer, "BEFORE")
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd, insertLayerThe following script will insert a layer called Rivers, from another, independant map document, above a layer called Lakes in a data frame called County Maps.
import arcpy
#Reference layer in secondary map document
mxd2 = arcpy.mapping.MapDocument(r"C:\Project\ProjectTemplate.mxd")
df2 = arcpy.mapping.ListDataFrames(mxd2, "Layers")[0]
insertLayer = arcpy.mapping.ListLayers(mxd2, "Rivers", df2)[0]
#Insert layer into primary map document
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "County Maps")[0]
refLayer = arcpy.mapping.ListLayers(mxd, "Lakes", df)[0]
arcpy.mapping.InsertLayer(df, refLayer, insertLayer, "BEFORE")
#Save to a new map document and clear variable references
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd, mxd2, insertLayer