TableFrameElement

Summary

The TableFrameElement class provides access to capabilities that allow you to modify how tabular information is displayed on the Layout class.

Discussion

A table frame element is a specialized map surround that has an associated MapFrame element and is also dynamically linked to a Layer or Table object to display its rows and fields. The listElements method on the Layout class returns a Python list of all possible layout elements. To return a list of only TableFrameElement objects, use the TABLEFRAME_ELEMENT constant for the element_type parameter. A wildcard value can also be used to further refine the search based on the element name value. It is important to uniquely name each layout element so it can be referenced using ArcPy scripting.

All the parameters that are available to the createTableFrameElement method of the Layout class are also exposed on theTableFrameElement class—such as mapframe, table, and fields—making changes to existing table frames possible. There are a number properties you can use to resize and position a table frame. You can also modify the appearance of a table frame using the sortFields method or control the rows that appear in the table using the setQuery method. Table frame elements also have getDefinition and setDefinition methods you can use to modify additional properties that are not exposed to the TableFrameElement class. Refer to the examples below and the Python CIM access help topic for more information.

Properties

Property	Explanation	Data Type
anchor (Read Only)	Returns one of the following string values that represent the current anchor position. To change the value, use the setAnchor method. BOTTOM_LEFT_CORNER—Bottom left corner position BOTTOM_MID_POINT—Bottom center position BOTTOM_RIGHT_CORNER—Bottom right corner position CENTER_POINT—Center position LEFT_MID_POINT—Left center position RIGHT_MID_POINT—Right center position TOP_LEFT_CORNER—Top left corner position TOP_MID_POINT—Top center position TOP_RIGHT_CORNER—Top right corner position	String
elementHeight (Read and Write)	The height of the element in page units.	Double
elementPositionX (Read and Write)	The x-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementPositionY (Read and Write)	The y-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementWidth (Read and Write)	The width of the element in page units.	Double
fields (Read and Write)	A list of strings that represent the table field names that are displayed in the table frame.	List
locked (Read and Write)	When set to True, the element cannot be graphically selected in the layout view.	Boolean
longName (Read Only)	An element's full name including group information if it exists. For example, an element named 'Table Frame' in a group element named 'Group Element' will return a longName value of 'Group Element\\Table Frame'. If the element is not in a group, the longName will be the same as the name value.	String
mapFrame (Read and Write)	A reference to the associated MapFrame.	MapFrame
name (Read and Write)	The name of the element. It is important that all elements have a unique name so they can be uniquely referenced using the wildcard parameter with the listElements function on the Layout object.	String
parentGroupElement (Read Only)	If the element is in a group, the value returned will be a GroupElement, otherwise a NoneType will be returned.	GroupElement
query (Read Only)	Returns one of the following string values that represent the current query that controls which rows should be displayed.. To change the value, use the setQuery method. ALL_ROWS—Display all rows in the table. MAPSERIES_ROWS—Display the row associated with the current index feature if a spatial map series is enabled. VISIBLE_ROWS—Display only the visible features in the map frame.	String
table (Read and Write)	The Layer or Table object associated with the table frame.	Object
type (Read Only)	Returns a value of TABLEFRAME_ELEMENT.	String
visible (Read and Write)	Returns True if the element is visible on the layout.	Boolean

Method Overview

Method	Explanation
applyStyleItem (style_item)	Applies a StyleItem to a TableFrameElement.
getDefinition (cim_version)	Returns a table frame element's CIM definition.
setAnchor (anchor)	The setAnchor method controls the anchor position for a TableFrameElement value.
setDefinition (definition_object)	The setDefinition method sets the CIM definition for a table frame element.
setQuery (query_rows)	The setQuery method controls the display of rows in the table frame.
sortFields (field_info)	The sortFields method sorts a table frame using a list of dictionary key-value pairs for one or many fields.

Methods

applyStyleItem (style_item)

Parameter	Explanation	Data Type
style_item	A reference to a StyleItem in a project.	StyleItem

When referencing a StyleItem using the listStyleItems method on the ArcGISProject class, the style_class parameter must be TABLE_FRAME. For more information and code samples, refer the to StyleItem help topic.

Note:

Styles must be added to a project prior to using the applyStyleItem method. They can be added using the updateStyles method on the ArcGISProject class.

getDefinition (cim_version)

Parameter	Explanation	Data Type
cim_version	A string that represents the major version of the CIM that will be used. V2—The 2.x version of the CIM will be used. V3—The 3.x version of the CIM will be used.	String

Return Value

Data Type	Explanation
Object	Returns the CIM definition for a TableFrameElement value.

For more information about working with the CIM and samples, see Python CIM access.

setAnchor (anchor)

Parameter	Explanation	Data Type
anchor	A string that specifies the location of the anchor position. BOTTOM_LEFT_CORNER—The anchor will be set at the bottom left corner position. BOTTOM_MID_POINT—The anchor will be set at the bottom center position. BOTTOM_RIGHT_CORNER—The anchor will be set at the bottom right corner position. CENTER_POINT—The anchor will be set at the center position. LEFT_MID_POINT—The anchor will be set at the left center position. RIGHT_MID_POINT—The anchor will be set at the right center position. TOP_LEFT_CORNER—The anchor will be set at the top left corner position. TOP_MID_POINT—The anchor will be set at the top center position. TOP_RIGHT_CORNER—The anchor will be set at the top right corner position.	String

Setting the anchor position is helpful because you can control how the element might expand when resized. For example, the default anchor position for a table frame element is TOP_LEFT_CORNER. If you change the anchor location to BOTTOM_RIGHT_CORNER, changing elementHeight will expand the element upward instead of downward (the default), and changing elementWidth will expand the element to the left.

setDefinition (definition_object)

Parameter	Explanation	Data Type
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

For more information about working with the CIM and samples, see Python CIM access.

setQuery (query_rows)

Parameter	Explanation	Data Type
query_rows	A keyword string that serves as a filter and specifies the rows that will be displayed in the table frame. ALL_ROWS—All rows in the table will be displayed. MAPSERIES_ROWS—The row associated with the current index feature will be displayed if a spatial map series is enabled. VISIBLE_ROWS—Only the visible features in the map frame will be displayed. (The default value is ALL_ROWS)	String

The default value is ALL_ROWS when creating a table frame. If you use the MAPSERIES_ROWS value, ensure that the Layout object has a spatial MapSeries value enabled; otherwise, you may not get the expected results.

sortFields (field_info)

Parameter	Explanation	Data Type
field_info [field_info,...]	A list of Python dictionaries that each contain field sorting information. The dictionary keys are defined below. name—A string that represents the name of the field used to sort. ascending—A Boolean value of True will sort in ascending order. The default value is True. caseSensitive—A Boolean value of True will honor case while sorting. The default value is True.	List

Sorting applies to all fields at once and is based on the order of the fields defined in the field_info list. You must re-create all the sorting information for all the relevant fields and pass that information into the field_info parameter.

Code sample

TableFrameElement example 1

The following script creates a table frame in a layout. Its uses a function to construct the envelop used to place the table frame on the layout.

def MakeRec_UL(ulx, uly, w, h):
    xyRecList = [[ulx, uly], [ulx+w, uly], [ulx+w,uly-h], [ulx,uly-h], [ulx,uly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rect = arcpy.Polygon(array)
    return rect

p = arcpy.mp.ArcGISProject('current')
m = p.listMaps('Map')[0]
lyr = m.listLayers('States*')[0]
lyt = p.listLayouts('Create*')[0]
mf = lyt.listElements()[0]

#States table frame
tfStyle = p.listStyleItems('ArcGIS 2D', 'TABLE_FRAME', 'Blue Alternating Rows')[0]
tfEnv = MakeRec_UL(0.5, 5, 7.5, 4)
tfFields = ['STATE_NAME', 'STATE_ABBR', 'POP2000', 'POP2010']
tf = lyt.createTableFrameElement(tfEnv, mf, lyr, tfFields, tfStyle, 'States TableFrame')

#Display only visible rows
tf.setQuery('VISIBLE_ROWS')

TableFrameElement example 2

The following script references an existing table frame and uses class methods to modify its appearance. The script makes additional changes to properties that are exposed via Python CIM access.

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Modify*')[0]
tf = lyt.listElements('TABLEFRAME_ELEMENT', 'States*')[0]

#Modify table frame
tf.setQuery('VISIBLE_ROWS')
tf.sort({'name':'STATE_NAME', 'ascending':True, 'caseSensitive':True})

#Modify additional properties using the CIM
tf_cim = tf.getDefinition('V3')
tf_cim.minFontSize = 8
tf_cim.alternate1RowBackgroundCount = 2
tf_cim.alternate2RowBackgroundCount = 2
tf_cim.balanceColumns = False
tf_cim.columnGap = 75
tf_cim.fittingStrategy = 'AdjustColumnsAndSize'
tf.setDefinition(tf_cim)

TableFrameElement example 3

The following script creates a spatial map series prior to creating a new table frame. It finishes by setting the query value to MAPSERIES_ROWS.

def MakeRec_UL(ulx, uly, w, h):
    xyRecList = [[ulx, uly], [ulx+w, uly], [ulx+w,uly-h], [ulx,uly-h], [ulx,uly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rect = arcpy.Polygon(array)
    return rect

p = arcpy.mp.ArcGISProject('current')
m = p.listMaps('Map')[0]
lyr = m.listLayers('GreatLakes')[0]
lyt = p.listLayouts('MapSeries')[0]
mf = lyt.listElements()[0]

#Create a spatial map series
lyt.createSpatialMapSeries(mf, lyr, 'NAME', 'AREA')

#Create a table frame
tfStyle = p.listStyleItems('ArcGIS 2D', 'TABLE_FRAME', 'Orange Alternating Rows')[0]
tfEnv = MakeRec_UL(0.5, 5.75, 7.5, 2)
tf = lyt.createTableFrameElement(tfEnv, mf, lyr, ['NAME', 'AREA'], tfStyle, 'Great Lakes TableFrame')

#Set the query to match mapseries rows
tf.setQuery('MAPSERIES_ROWS')