Summary
Provides the ability to add a layer to a group layer within a map document (.mxd) using simple placement options.
Discussion
AddLayerToGroup is an easy way to add a layer into an already existing group layer. It can add a layer with auto-arrange logic that places the new layer in a group layer similarly to how the Add Data button works in ArcMap; it places the layer based on layer weight rules and geometry type. The other placement choices are either at the top or the bottom of a group layer.
AddLayerToGroup is the only function that can add a layer into an empty group layer. AddLayerToGroup does not allow you to add layers to group layers within a layer file. Layer files should be managed and authored using ArcMap.
The target group layer must be a group layer. The isGroupLayer property on the Layer object is a way of confirming if the returned Layer object is truely a group layer.
The layer that is added 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 AddLayerToGroup.
Syntax
AddLayerToGroup (data_frame, target_group_layer, add_layer, {add_position})| Parameter | Explanation | Data Type |
data_frame | A reference to a DataFrame object that contains the group layer to which the new layer will be added. | DataFrame |
target_group_layer | A Layer object representing the group layer to which the new layer will be added. It must be a group layer. | Layer |
add_layer | A reference to a Layer object representing the layer to be added. This reference can point to a layer file on disk or a layer in a map document. | Layer |
add_position | A constant that determines the placement of the added layer within a data frame.
(The default value is AUTO_ARRANGE) | String |
Code sample
The following script will add a new layer from a layer (.lyr) file on disk and place it at the bottom of a group layer called 24000 Scale Data 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]
targetGroupLayer = arcpy.mapping.ListLayers(mxd, "24000 Scale Data", df)[0]
addLayer = arcpy.mapping.Layer(r"C:\Project\Data\StreetsWithLabels.lyr")
arcpy.mapping.AddLayerToGroup(df, targetGroupLayer, addLayer, "BOTTOM")
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd, addLayer