Best Practices for Accessing Component IDs

To refer to a Visualforce component in JavaScript or another Web-enabled language, you must specify a value for the id attribute for that component. A DOM ID is constructed from a combination of the id attribute of the component and the id attributes of all components that contain the element.

Use the $Component global variable to simplify referencing the DOM ID that is generated for a Visualforce component, and reduce some of the dependency on the overall page structure. To reference a specific Visualforce component’s DOM ID, add a component path specifier to $Component, using dot notation to separate each level in the component hierarchy of the page. For example, use $Component.itemId to reference a component at the same level in the Visualforce component hierarchy, or use $Component.grandparentId.parentId.itemId to specify a more complete component path.

A $Component path specifier is matched against the component hierarchy:

At the current level of the component hierarchy where $Component is used; and then
At each successive higher level in the component hierarchy, until a match is found, or the top-level of the component hierarchy is reached.

There is no backtracking, so if the ID you’re trying to match requires a traversal up and then back down, it won’t match.

The following example illustrates several uses of $Component:

1swfobject.registerObject("clippy.codeblock-0", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17<apex:page >
18
19    <style>
20    .clicker { border: 1px solid #999; cursor: pointer;
21        margin: .5em; padding: 1em; width: 10em; text-align: center; }
22    </style>
23
24    <apex:form id="theForm">
25        <apex:pageBlock id="thePageBlock" title="Targeting IDs with $Component">
26            <apex:pageBlockSection id="theSection">
27                <apex:pageBlockSectionItem id="theSectionItem">
28                    All the alerts refer to this component.
29                    
30                    <p>The full DOM ID resembles something like this:<br/>
31                    j_id0:theForm:thePageBlock:theSection:theSectionItem</p>
32                </apex:pageBlockSectionItem>
33
34                <!-- Works because this outputPanel has a parent in common 
35                     with "theSectionItem" component -->
36                <apex:outputPanel layout="block" styleClass="clicker"
37                    onclick="alert('{!$Component.theSectionItem}');">
38                    First click here
39                </apex:outputPanel>
40            </apex:pageBlockSection>
41            
42            <apex:pageBlockButtons id="theButtons" location="bottom">
43                <!-- Works because this outputPanel has a grandparent ("theSection")
44                     in common with "theSectionItem" -->
45                <apex:outputPanel layout="block" styleClass="clicker"
46                    onclick="alert('{!$Component.theSection.theSectionItem}');">
47                    Second click here
48                </apex:outputPanel>
49
50                <!-- Works because this outputPanel has a distant ancestor ("theForm")
51                     in common with "theSectionItem" -->
52                <apex:outputPanel layout="block" styleClass="clicker"
53                    onclick="alert('
54                    {!$Component.theForm.thePageBlock.theSection.theSectionItem}');">
55                    Third click here
56                </apex:outputPanel>
57            </apex:pageBlockButtons>
58
59        </apex:pageBlock>
60
61        <!-- Works because this outputPanel is a sibling to "thePageBlock",
62             and specifies the complete ID path from that sibling -->
63        <apex:outputPanel layout="block" styleClass="clicker"
64            onclick="alert('{!$Component.thePageBlock.theSection.theSectionItem}');">
65            Fourth click here
66        </apex:outputPanel>
67        
68        <hr/>
69        
70        <!-- Won't work because this outputPanel doesn't provide a path 
71             that includes a sibling or common ancestor -->
72        <apex:outputPanel layout="block" styleClass="clicker"
73            onclick="alert('{!$Component.theSection.theSectionItem}');">
74            This won't work
75        </apex:outputPanel>
76
77        <!-- Won't work because this outputPanel doesn't provide a path 
78             that includes a sibling or common ancestor -->
79        <apex:outputPanel layout="block" styleClass="clicker"
80            onclick="alert('{!$Component.theSectionItem}');">
81            Won't work either
82        </apex:outputPanel>
83
84    </apex:form>
85</apex:page>

Using Unique IDs

Within each hierarchy segment in a page, the component id must be unique. However, Salesforce recommends you use an id that is unique on the page for every component you need to reference, and any components above it in the component hierarchy that are needed to reference it.

For example, suppose you had two data tables in a single page. If both data tables are contained in the same page block, they must have unique id attributes. If each is contained in a separate page block, it’s possible to give them the same component id. If you do so, however, the only way to reference a specific data table is to assign an id to every component and then reference the data table component using the complete hierarchy, rather than letting Visualforce do it automatically. If the page hierarchy ever changes, your program will no longer work.

Iterating with Component IDs

Some components, such as tables and lists, support iteration over a collection of records. After you assign an ID for these types of components, the system assigns a unique “compound ID” to each iteration of the component based on the initial ID.

For example, the following page contains a data table with an ID set to theTable.

1swfobject.registerObject("clippy.codeblock-1", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17<apex:page standardController="Account" recordSetVar="accounts" id="thePage">
18    <apex:dataTable value="{!accounts}" var="account" id="theTable">
19        <apex:column id="firstColumn">
20            <apex:outputText value="{!account.name}"/>
21        </apex:column>
22        <apex:column id="secondColumn">
23            <apex:outputText value="{!account.owner.name}"/>
24        </apex:column>
25    </apex:dataTable>
26</apex:page>

When the page is rendered, the <apex:dataTable> component results in the following HTML:

1<table id="thePage:theTable" border="0" cellpadding="0" cellspacing="0">
2<colgroup span="2"/>
3<tbody>
4    <tr class="">
5        <td id="thePage:theTable:0:firstColumn">
6            <span id="thePage:theTable:0:accountName">Burlington Textiles</span>
7        </td>
8        <td id="thePage:theTable:0:secondColumn">
9            <span id="thePage:theTable:0:accountOwner">Vforce Developer</span>
10        </td>
11    </tr>
12    <tr class="">
13        <td id="thePage:theTable:1:firstColumn">
14            <span id="thePage:theTable:1:accountName">Dickenson</span>
15        </td>
16        <td id="thePage:theTable:1:secondColumn">
17            <span id="thePage:theTable:1:accountOwner">Vforce Developer</span>
18        </td>
19    </tr>
20</table>

Each table cell has a unique ID based on the ID value of the containing components. The first table cell in the first row has the ID thePage:theTable:0:firstColumn, the second cell in the first row has the ID thePage:theTable:0:secondColumn, the first cell in the second row has the ID thePage:theTable:1:firstColumn, and so on.

To refer to all entries in a column, you have to iterate across the table rows, referring to each <td> element that has an ID following the format of the column.

The same type of ID generation is done for elements within the table cells. For example, the account name in the first row is generated as a span with the ID thePage:theTable:0:accountName. Notice that ID does not include the value of the ID for the column it’s in.

Visualforce Developer’s Guide

Best Practices for Accessing Component IDs

Using Unique IDs

Iterating with Component IDs