Getting ready

The AddLayer() function simply adds a layer into a data frame or a group layer, and places the layer automatically using auto-arrange or specific placement at the top or bottom of the data frame or group layer. The InsertLayer() method allows for more precise positioning of a new layer into a data frame or a group layer. It uses a reference layer to specify a location and the layer is added either before or after the reference layer, as specified in your code. Since InsertLayer() requires the use of a reference layer, you can't use this method on an empty data frame.

This is illustrated in the following screenshot, where District_Crime_Join is the reference layer and School_Districts is the layer to be added. The School_Districts layer can be placed either before or after the reference layer using InsertLayer().

How to do it…

Follow these steps to learn how to use InsertLayer() to insert a layer into a data frame:

How it works…

After obtaining references to the arcpy.mapping module, current map document file, and the Crime data frame, our script then defines a reference layer. In this case, we use the ListLayers() function with a wildcard of Burglaries*, and the Crime data frame to restrict the list of layers returned to only one item. This item will be the Burglaries in 2009 layer. We use Python list access with a value of 0 to retrieve this layer from the list and assign it to a Layer object. Next, we define the insert layer, which is a new Layer object that references the Crimes2009 feature class from the CityOfSanAntonio geodatabase database. Finally, we call the InsertLayer() function passing in the data frame, reference layer, layer to be inserted, and keyword indicating that the layer to be inserted should be placed before the reference layer. This is illustrated in the following screenshot:

There's more…

You can also reposition a layer that is already in a data frame or a group layer. The MoveLayer() function provides the ability to reposition the layer within a data frame or a group layer. Movement of a layer must be within the same data frame. You can't move a layer from one data frame to another. Just as with InsertLayer(), MoveLayer() uses a reference layer to reposition the layer.