CHAPTER 6
Standard List Controllers
Standard list controllers allow you to create Visualforce pages that can display or act on a set of records. Examples of existing Salesforce pages that work with a set of records include list pages, related lists, and mass action pages. Standard list controllers can be used with the following objects:
•
Account
•
Asset
•
Campaign
•
Case
•
Contact
•
Contract
•
Idea
•
Lead
•
Opportunity
•
Order
•
Product2
•
Solution
•
User
•
Custom objects
The following topics include additional information about using standard list controllers:
•
Associating a Standard List Controller with a Visualforce Page
•
Accessing Data with List Controllers
•
Using Standard List Controller Actions
•
Using List Views with Standard List Controllers
•
Overriding Tabs Using a Standard List Controller
•
Adding Custom List Buttons using Standard List Controllers
SEE ALSO:
Building a Custom Controller
Associating a Standard List Controller with a Visualforce Page
Using a standard list controller is very similar to using a standard controller. First you set the standardController
attribute on the
<apex:page >
component, then you set the recordSetVar
attribute on the same component.
79
Standard List Controllers Accessing Data with List Controllers
For example, to associate a page with the standard list controller for accounts, use the following markup:
<apex:page standardController= "Account" recordSetVar= "accounts" >
Note: When you use the standardController
attribute on the
<apex:page >
tag, you can’t use the controller attribute at the same time.
The recordSetVar
attribute not only indicates that the page uses a list controller, it sets the variable name of the record collection.
This variable can be used to access data in the record collection.
Accessing Data with List Controllers
Once you have associated a page with a list controller, you can refer to the set of records using expression language syntax. For example, to create a simple table of accounts, create a page with the following markup:
<apex:page standardController= "Account" recordSetVar= "accounts" tabstyle= "account" sidebar= "false" >
<apex:pageBlock >
<apex:pageBlockTable value= "{!accounts}" var= "a" >
<apex:column value= "{!a.name}" />
</apex:pageBlockTable >
</apex:pageBlock >
</apex:page >
This results in a page that lists all the account names in your organization:
Note: This page does not specify a filter in the request, so the page is displayed with the last used filter. For information on using filters with list controllers, see
Using List Views with Standard List Controllers
on page 82.
As with queries in the Force.com API, you can use expression language syntax to retrieve data from related records. As with standard controllers, you can traverse up to five levels of child-to-parent relationships and one level of parent-to-child relationships.
When using a standard list controller, the returned records sort on the first column of data, as defined by the current view, even if that
column is not rendered. When using an extension or custom list controller , you can control the sort method.
Note:
No more than 10,000 records can be returned by a standard list controller. Custom controllers can work with larger results
sets. See Working with Large Sets of Data on page 96.
SEE ALSO:
Force.com SOQL and SOSL Reference: Relationship Queries
80
Standard List Controllers Using Standard List Controller Actions
Using Standard List Controller Actions
Action methods perform logic or navigation when a page event occurs, such as when a user clicks a button, or hovers over an area of the page. Action methods can be called from page markup by using
{! }
notation in the action
parameter of one of the following tags:
•
<apex:commandButton >
creates a button that calls an action
•
<apex:commandLink >
creates a link that calls an action
•
<apex:actionPoller >
periodically calls an action
•
<apex:actionSupport >
makes an event (such as “onclick”, “onmouseover”, and so on) on another, named component, call an action
•
<apex:actionFunction >
defines a new JavaScript function that calls an action
•
<apex:page >
calls an action when the page is loaded
The following table describes the action methods that are supported by all standard list controllers. You can associate these actions with any Visualforce component that includes an action
attribute.
Action
save quicksave list cancel first last next previous
Description
Inserts new records or updates existing records that have been changed. After this operation is finished, the save
action returns the user to the original page, if known, or the home page.
Inserts new records or updates existing records that have been changed. Unlike the save
action, quicksave
does not redirect the user to another page.
Returns a PageReference object of the standard list page, based on the most recently used list filter for that object when the filterId
is not specified by the user.
Aborts an edit operation. After this operation is finished, the cancel
action returns the user to the page where the user originally invoked the edit.
Displays the first page of records in the set.
Displays the last page of records in the set.
Displays the next page of records in the set.
Displays the previous page of records in the set.
In the following example, the user specifies a filter for viewing account records. When the user clicks Go, the standard list page displays, using the selected filter.
<apex:page standardController= "Account" recordSetVar= "accounts" >
<apex:form >
<apex:selectList value= "{!filterid}" size= "1" >
<apex:selectOptions value= "{!listviewoptions}" />
</apex:selectList >
<apex:commandButton value= "Go" action= "{!list}" />
</apex:form >
</apex:page >
81
Standard List Controllers Pagination with a List Controller
Pagination with a List Controller
You can add pagination to a page using a list controller by utilizing the next
and previous
actions. For example, if you create a page with the following markup:
<apex:page standardController= "Account" recordSetvar= "accounts" >
<apex:pageBlock title= "Viewing Accounts" >
<apex:form id= "theForm" >
<apex:pageBlockSection >
<apex:dataList var= "a" value= "{!accounts}" type= "1" >
{!a.name}
</apex:dataList >
</apex:pageBlockSection >
<apex:panelGrid columns= "2" >
<apex:commandLink action= "{!previous}" >Previous </apex:commandlink >
<apex:commandLink action= "{!next}" >Next </apex:commandlink >
</apex:panelGrid >
</apex:form >
</apex:pageBlock >
</apex:page >
By default, a list controller returns 20 records on the page. To control the number of records displayed on each page, use a controller extension to set the pageSize
. For information on controller extensions, see
Building a Controller Extension on page 89.
Note: When you use pagination, an exception is thrown when there are modified rows in the collection. This includes any new rows added to the collection through an extension action. The handling of error messages in this case follows the standard behavior and can either be displayed upon the page. For example, you can use the
<apex:pageMessages >
or
<apex:messages > component to display an error message to the user.
Using List Views with Standard List Controllers
Many Salesforce pages include list views that allow you to filter the records displayed on the page. For example, on the opportunities home page, you can choose to view a list of only the opportunities you own by selecting
My Opportunities
from the list view drop-down. On a page that is associated with a list controller, you can also use list views.
For example, to create a simple list of accounts with a list view, create a page with the following markup:
<apex:page standardController= "Account" recordSetvar= "accounts" >
<apex:pageBlock title= "Viewing Accounts" >
<apex:form id= "theForm" >
<apex:panelGrid columns= "2" >
<apex:outputLabel value= "View:" />
<apex:selectList value= "{!filterId}" size= "1" >
<apex:actionSupport event= "onchange" rerender= "list" />
<apex:selectOptions value= "{!listviewoptions}" />
</apex:selectList >
</apex:panelGrid >
<apex:pageBlockSection >
<apex:dataList var= "a" value= "{!accounts}" id= "list" >
{!a.name}
</apex:dataList >
</apex:pageBlockSection >
</apex:form >
82
Standard List Controllers
</apex:pageBlock >
</apex:page >
When you open that page, you'll see something like the following:
Using List Views with Standard List Controllers
This page is associated with the standard account controller and the
<apex:selectlist >
component is populated by
{!listviewoptions}
, which evaluates to the list views the user can see. When the user chooses a value from the drop-down list, it is bound to the filterId
property for the controller. When the filterId
is changed, the records available to the page changes, so, when the
<apex:datalist >
is updated, that value is used to update the list of records available to the page.
You can also use a view list on an edit page, like the following:
<apex:page standardController= "Opportunity" recordSetVar= "opportunities" tabStyle= "Opportunity" sidebar= "false" >
<apex:form >
<apex:pageBlock >
<apex:pageMessages/ >
<apex:pageBlock >
<apex:panelGrid columns= "2" >
<apex:outputLabel value= "View:" />
<apex:selectList value= "{!filterId}" size= "1" >
<apex:actionSupport event= "onchange" rerender= "opp_table" />
<apex:selectOptions value= "{!listviewoptions}" />
</apex:selectList >
</apex:panelGrid >
</apex:pageBlock >
<apex:pageBlockButtons >
<apex:commandButton value= "Save" action= "{!save}" />
</apex:pageBlockButtons >
<apex:pageBlockTable value= "{!opportunities}" var= "opp" id= "opp_table" >
<apex:column value= "{!opp.name}" />
<apex:column headerValue= "Stage" >
<apex:inputField value= "{!opp.stageName}" />
</apex:column >
<apex:column headerValue= "Close Date" >
<apex:inputField value= "{!opp.closeDate}" />
</apex:column >
</apex:pageBlockTable >
</apex:pageBlock >
83
Standard List Controllers Editing Records with List Controllers
</apex:form >
</apex:page >
Note: If the user changes the list view, an exception is thrown if there are modified rows in the collection. The handling of error messages in this case follows the standard behavior and can either be displayed upon the page. For example, you can use the
<apex:pageMessages >
or
<apex:messages >
component to display an error message to the user.
Editing Records with List Controllers
You can edit a set of records using list controllers, too. For example, if you create a page with the following markup:
<apex:page standardController= "Opportunity" recordSetVar= "opportunities" tabStyle= "Opportunity" sidebar= "false" >
<apex:form >
<apex:pageBlock >
<apex:pageMessages />
<apex:pageBlockButtons >
<apex:commandButton value= "Save" action= "{!save}" />
</apex:pageBlockButtons >
<apex:pageBlockTable value= "{!opportunities}" var= "opp" >
<apex:column value= "{!opp.name}" />
<apex:column headerValue= "Stage" >
<apex:inputField value= "{!opp.stageName}" />
</apex:column >
<apex:column headerValue= "Close Date" >
<apex:inputField value= "{!opp.closeDate}" />
</apex:pageBlock >
</apex:form >
</apex:page >
</apex:column >
</apex:pageBlockTable > you see a page that allows you to update and save the
Stage
and
Close Date
on your opportunities, like the following:
84
Standard List Controllers Editing Records with List Controllers
For more information, see Mass-Updating Records with a Custom List Controller
on page 136.
Note: Command buttons and links that are associated with save
, quicksave
, or edit
actions in a list controller are not rendered if the user does not have the appropriate permissions. Likewise if no particular record is associated with a page, command buttons and links associated with the edit
actions are not rendered.
85
