Visualforce Developer Guide

Introducing Visualforce
Tools for Visualforce Development
Getting a Quick Start with Visualforce
Customizing the Appearance and Output of Visualforce Pages
Standard Controllers
Standard List Controllers
Custom Controllers and Controller Extensions
What are Custom Controllers and Controller Extensions?
Building a Custom Controller
Building a Controller Extension
Building a Custom List Controller
Controller Methods
Controller Class Security
Working with Large Sets of Data
Considerations for Creating Custom Controllers and Controller Extensions
Order of Execution in a Visualforce Page
Testing Custom Controllers and Controller Extensions
Validation Rules and Custom Controllers
Using the transient Keyword
Advanced Examples
Overriding Buttons, Links, and Tabs with Visualforce
Using Static Resources
Creating and Using Custom Components
Dynamic Visualforce Bindings
Dynamic Visualforce Components
Integrating Email with Visualforce
Visualforce Charting
Creating Maps with Visualforce
Render Flows with Visualforce
Templating with Visualforce
Developing for Mobile Devices
Adding Visualforce to a Force.com AppExchange App
Using JavaScript in Visualforce Pages
Best Practices
Standard Component Reference
Appendices
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Controller Methods

Visualforce markup can use the following types of controller extension and custom controller methods:
  • Action
  • Getter
  • Setter

Action Methods

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:

For example, in the sample page in Building a Custom Controller, the controller's save method is called by the action parameter of the <apex:commandButton> tag. Other examples of action methods are discussed in Defining Action Methods.

Getter Methods

Getter methods return values from a controller. Every value that is calculated by a controller and displayed in a page must have a corresponding getter method, including any Boolean variables. For example, in the sample page in Building a Custom Controller, the controller includes a getAccount method. This method allows the page markup to reference the account member variable in the controller class with {! } notation. The value parameter of the <apex:inputField> tag uses this notation to access the account, and dot notation to display the account's name. Getter methods must always be named getVariable.

It’s a best practice for getter methods to be idempotent, that is, to not have side effects. For example, don’t increment a variable, write a log message, or add a new record to the database. Visualforce doesn’t define the order in which getter methods are called, or how many times they might be called in the course of processing a request. Design your getter methods to produce the same outcome, whether they are called once or multiple times for a single page request.

Important

Setter Methods

Setter methods pass user-specified values from page markup to a controller. Any setter methods in a controller are automatically executed before any action methods.

For example, the following markup displays a page that implements basic search functionality for Leads. The associated controller includes getter and setter methods for the search box input, and then uses the search text to issue a SOSL query when the user clicks Go!. Although the markup doesn’t explicitly call the search text setter method, it executes before the doSearch action method when a user clicks the command button:

The following class is the controller for the page markup above:

While a getter method is always required to access values from a controller, it’s not always necessary to include a setter method to pass values into a controller. If a Visualforce component is bound to an sObject that is stored in a controller, the sObject's fields are automatically set if changed by the user, as long as the sObject is saved or updated by a corresponding action method. An example of this behavior is shown in the sample page in Building a Custom Controller.

Setter methods must always be named setVariable.

It’s a best practice for setter methods to be idempotent, that is, to not have side effects. For example, don’t increment a variable, write a log message, or add a new record to the database. Visualforce doesn’t define the order in which setter methods are called, or how many times they might be called in the course of processing a request. Design your setter methods to produce the same outcome, whether they are called once or multiple times for a single page request.

Important

Getting and Setting Data with a Custom Extension or Controller

There is no guaranteed order in which Apex methods and variables are processed by a controller extension or custom controller. Therefore, do not allow controller and extension classes to rely on another method being run, call that method directly. This applies specifically to setting variables and accessing data from the database.

For example, in the following custom controller, the first method, getContactMethod1, always returns the correct value because it doesn’t assume that the contact variable c already exists. The second method, getContactMethod2, however, sometimes returns the correct value, but not every time if c hasn’t yet been set.

The following custom controller has the exact same methods. However, getContactMethod2 calls contactMethod1, so the variable c is always set, and always contains the correct value when returned.

The following markup shows two pages that call these controllers. The Visualforce markup is identical, only the controller name is changed: