Professional Documents
Culture Documents
Custom Controllers and Controller Extensions - Visualforce
Custom Controllers and Controller Extensions - Visualforce
Standard controllers can provide all the functionality you need for a Visualforce page because they include the same
logic that is used for a standard page. For example, if you use the standard Accounts controller, clicking
a Save button in a Visualforce page results in the same behavior as clicking Save on a standard Account edit page.
However, if you want to override existing functionality, customize the navigation through an application, use
callouts or Web services, or if you need finer control for how information is accessed for your page, you can write a
custom controller or a controller extension using Apex:
You want to leverage the built-in functionality of a standard controller but override one or more actions, such as
edit, view, save, or delete.
You want to add new actions.
You want to build a Visualforce page that respects user permissions. Although a controller extension class
executes in system mode, if a controller extension extends a standard controller, the logic from the standard
controller does not execute in system mode. Instead, it executes in user mode, in which permissions, field-level
security, and sharing rules of the current user apply.
Although custom controllers and controller extension classes execute in system mode and thereby ignore user
permissions and field-level security, you can choose whether they respect a user's organization-wide defaults, role
hierarchy, and sharing rules by using the with sharing keywords in the class definition. For information, see “Using
the with sharing, without sharing, and inherited sharing Keywords” in the Apex Developer Guide.
Building a Custom Controller
A custom controller is an Apex class that uses the default, no-argument constructor for the outer, top-level class.
You cannot create a custom controller constructor that includes parameters.
To create a custom controller:
1. From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
2. Click New.
3. Click Version Settings to specify the version of Apex and the API used with this class. If your organization has
installed managed packages from the AppExchange, you can also specify which version of each managed
package to use with this class. Use the default values for all versions. This associates the class with the most
recent version of Apex and the API, as well as each managed package. You can specify an older version of a
managed package if you want to access components or functionality that differs from the most recent package
version. You can specify an older version of Apex and the API to maintain specific behavior.
4. In the class editor, enter the Apex code for the class. A single class can be up to 1 million characters in length,
not including comments, test methods, or classes defined using @isTest.
5. Click Save to save your changes and return to the class detail screen, or click Quick Save to save your changes
and continue editing your class. Your Apex class must compile correctly before you can save your class.
05 public MyController() {
06 account = [SELECT Id, Name, Site FROM Account
07 WHERE Id = :ApexPages.currentPage().getParameters().get('id')];
08 }
09
10 public Account getAccount() {
11 return account;
12 }
13
14 public PageReference save() {
15 update account;
16 return null;
17 }
18 }
The following Visualforce markup shows how the custom controller above can be used in a page:
1 <apex:page controller="myController" tabStyle="Account">
2 <apex:form>
The custom controller is associated with the page because of the controller attribute of
the <apex:page> component.
As with standard controllers and controller extensions, custom controller methods can be referenced
with {! } notation in the associated page markup. In the example above, the getAccount method is referenced by
the <apex:inputField> tag's value attribute, while the <apex:commandButton> tag references the save method
with its action attribute.
Like other Apex classes, all custom controllers run in system mode. Consequently, the current user's credentials are
not used to execute controller logic, and the user's permissions and field-level security do not apply.
You can choose whether a custom controller respects a user's organization-wide defaults, role hierarchy, and sharing
rules by using the with sharing keywords in the class definition. For information, see “Using the with
sharing, without sharing, and inherited sharing Keywords” in the Apex Developer Guide.
A custom controller can also be used to create new records. For example:
01 public class NewAndExistingController {
02
03 public Account account { get; private set; }
04
05 public NewAndExistingController() {
06 Id id = ApexPages.currentPage().getParameters().get('id');
07 account = (id == null) ? new Account() :
08 [SELECT Name, Phone, Industry FROM Account WHERE Id = :id];
09 }
10
11 public PageReference save() {
12 try {
13 upsert(account);
14 } catch(System.DMLException e) {
15 ApexPages.addMessages(e);
16 return null;
17 }
18 // After successful Save, navigate to the default view page
PageReference redirectSuccess
19
= new ApexPages.StandardController(Account).view();
20 return (redirectSuccess);
21 }
22 }
The following Visualforce markup shows how the custom controller above can be used in a page:
01 <apex:page controller="NewAndExistingController" tabstyle="Account">
02 <apex:form>
03 <apex:pageBlock mode="edit">
04 <apex:pageMessages/>
05 <apex:pageBlockSection>
06 <apex:inputField value="{!Account.name}"/>
07 <apex:inputField value="{!Account.phone}"/>
08 <apex:inputField value="{!Account.industry}"/>
09 </apex:pageBlockSection>
10 <apex:pageBlockButtons location="bottom">
11 <apex:commandButton value="Save" action="{!save}"/>
12 </apex:pageBlockButtons>
13 </apex:pageBlock>
14 </apex:form>
15 </apex:page>
02
04
07 // controller.
10 }
11
14 }
15 }
The following Visualforce markup shows how the controller extension from above can be used in a page:
1 <apex:page standardController="Account" extensions="myControllerExtension">
2 {!greeting} <p/>
3 <apex:form>
6 </apex:form>
7 </apex:page>
The extension is associated with the page using the extensions attribute of the <apex:page> component.
As with all controller methods, controller extension methods can be referenced with {! } notation in page markup.
In the example above, the {!greeting} expression at the top of the page references the controller
extension's getGreeting method.
Because this extension works in conjunction with the Account standard controller, the standard controller methods
are also available. For example, the value attribute in the <apex:inputField> tag retrieves the name of the account
using standard controller functionality. Likewise, the <apex:commandButton> tag references the standard
account save method with its action attribute.
Multiple controller extensions can be defined for a single page through a comma-separated list. This allows for
overrides of methods with the same name. For example, if the following page exists:
1 <apex:page standardController="Account"
2 extensions="ExtOne,ExtTwo" showHeader="false">
4 </apex:page>
5 return 'foo-One';
6 }
7}
5 return 'foo-Two';
6 }
7}
The value of the <apex:outputText> component renders as foo-One. Overrides are defined by whichever methods
are defined in the “leftmost” extension, or, the extension that is first in the comma-separated list. Thus,
the getFoo method of ExtOne is overriding the method of ExtTwo.
Like other Apex classes, controller extensions run in system mode. Consequently, the current user's credentials are
not used to execute controller logic, and the user's permissions and field-level security do not apply. However, if a
controller extension extends a standard controller, the logic from the standard controller does not execute in system
mode. Instead, it executes in user mode, in which the permissions, field-level security, and sharing rules of the
current user apply.
You can choose whether a controller extension respects a user's organization-wide defaults, role hierarchy, and
sharing rules by using the with sharing keywords in the class definition. For information, see “Using the with
sharing, without sharing, and inherited sharing Keywords” in the Apex Developer Guide.
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:
<apex:actionSupport> makes an event (such as “onclick”, “onmouseover”, and so on) on another, named
component, call an action
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.
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:
01 <apex:page controller="theController">
02 <apex:form>
04 <apex:pageBlockSection>
05 <apex:pageBlockSectionItem>
07 <apex:panelGroup>
10 rerender="block" status="status"/>
11 </apex:panelGroup>
12 </apex:pageBlockSectionItem>
13 </apex:pageBlockSection>
17 rendered="{!NOT(ISNULL(results))}">
18 <apex:column value="{!l.name}"/>
19 <apex:column value="{!l.email}"/>
20 <apex:column value="{!l.phone}"/>
21 </apex:pageBlockTable>
22 </apex:pageBlockSection>
23 </apex:pageBlock>
24 </apex:form>
25 </apex:page>
The following class is the controller for the page markup above:
01 public class theController {
02
03 String searchText;
04 List<Lead> results;
05
07 return searchText;
08 }
09
11 searchText = s;
12 }
13
15 return results;
16 }
17
20 return null;
21 }
22 }
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.
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.
01 public class conVsBad {
02 Contact c;
03
06 return c;
07 }
08
10 return c;
11 }
12 }
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.
01 public class conVsGood {
02 Contact c;
03
06 return c;
07 }
08
10 return getContactMethod1();
11 }
12 }
The following markup shows two pages that call these controllers. The Visualforce markup is identical, only the
controller name is changed:
1 <apex:page controller="conVsGood">
2 getContactMethod2(): {!contactMethod2.name}<br/>
3 getContactMethod1(): {!contactMethod1.name}
4 </apex:page>
view source
print?
1 <apex:page controller="conVsBad">
2 getContactMethod2(): {!contactMethod2.name}<br/>
3 getContactMethod1(): {!contactMethod1.name}
4 </apex:page>
If you’ve installed a managed package in your org, you can set security only for the Apex classes in the package that
are declared as global or for classes that contain methods declared as webService.
If users have the Author Apex permission, they can access all Apex classes in the associated organization, regardless
of the security settings for individual classes.
Permission for an Apex class is checked only at the top level. For example, class A calls class B. User X has a
profile that can access class A but not class B. User X can execute the code in class B, but only through class A; user
X cannot invoke class B directly. Likewise, if a Visualforce page uses a custom component with an associated
controller, security is only checked for the controller associated with the page. The controller associated with the
custom component executes regardless of permissions.
To set Apex class security from the class list page:
1. From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
2. Next to the name of the class that you want to restrict, click Security.
3. Select the profiles that you want to enable from the Available Profiles list and click Add, or select the profiles
that you want to disable from the Enabled Profiles list and click Remove.
4. Click Save.
Unless a class has a method defined as webService, custom extension and controller classes and methods are
generally defined as public. If a class includes a web service method, it must be defined as global.
Use sets, maps, or lists when returning data from the database. This makes your code more efficient because the
code makes fewer trips to the database.
The Apex governor limits for Visualforce controller extensions and custom controllers are the same as the limits
for anonymous block or WSDL methods. For more information about governor limits, see Execution Governors
and Limits in the Appendix.
If you are building a custom controller or controller extension, be careful that you do not inadvertently expose
sensitive data that would normally be hidden from users. Consider using the with sharing keywords on class
definitions to enforce permissions. Also be careful using Web services, which are secured as top-level entry
points by the profile, but execute in the system context once they are initiated.
Apex methods and variables are not instantiated in a guaranteed order. For more information, see Getting and
Setting Data with a Custom Extension or Controller.
You can't use data manipulation language (DML) operations in a “getxxx” method in a controller. For example,
if your controller had a getName method, you could not use insert or update in the method to create an object.
You can't use data manipulation language (DML) operations in a constructor method in a controller.
You can't use the @future annotation in a “getxxx” or “setxxx” method in a controller, or in the constructor for a
controller.
Primitive Apex data types such as String or Integer are passed by value to the component's controller.
Non-primitive Apex data types such as lists and sObjects are passed by reference to component's controller. This
means that if component's controller changes the name of an account, the changes are available in page's
controller.
If your org uses person accounts
o When referencing an account record's name field with a custom controller using
the <apex:inputField> component you must specify isPersonAccount in your query.
o If you create a new account and set name, the record will be a business account. If you create a new account
and set lastname, it will be a person account.
o As a best practice, create a custom name formula field that will render properly for both person accounts and
business accounts, then use that field instead of the standard field in your Visualforce pages.
o If you plan on including your Visualforce page in a Salesforce AppExchange package, in your controller or
controller extension, you cannot explicitly reference fields that exist only in a person account.
A get request is an initial request for a page either made when a user enters an URL or when a link or button is
clicked that takes the user to a new page.
A postback request is made when user interaction requires a page update, such as when a user clicks on
a Save button and triggers a save action.
For specific details of the two types of requests, examples illustrating the lifecycle of a page, and tips on how to
handle execution order when writing your own custom controllers and controller extensions, see:
The maximum response size from a Visualforce page request must be below 15 MB.
02
08
09 public thecontroller() {
10 this.qp = ApexPages.currentPage().getParameters().get('qp');
11 }
12
14 return this.firstName;
15 }
16
18 this.firstName = firstName;
19 }
20
22 return this.lastName;
23 }
24
26 this.lastName = lastName;
27 }
28
30 return this.company;
31 }
32
35 }
36
38 return this.email;
39 }
40
42 this.email = email;
43 }
44
46 PageReference p = null;
47
49 p = Page.failure;
50 p.getParameters().put('error', 'noParam');
51 } else {
52 try {
54 FirstName=this.firstName,
55 Company=this.company,
56 Email=this.email);
57 insert newlead;
58 } catch (Exception e) {
59 p = Page.failure;
60 p.getParameters().put('error', 'noInsert');
61 }
62 }
63
64 if (p == null) {
65 p = Page.success;
66 }
67
68 p.setRedirect(true);
69 return p;
70 }
71 }
The controller calls two additional pages: a success page and a failure page. The text of those pages is not important
for this example. They merely have to exist.
The following markup uses the controller above:
01 <apex:page controller="thecontroller" tabstyle="lead">
02 <apex:pageBlock>
03 <apex:form>
11 </apex:form>
12 </apex:pageBlock>
13 </apex:page>
03
06 Test.setCurrentPage(pageRef);
07
08 thecontroller controller = new thecontroller();
10
12 System.assertEquals('/apex/failure?error=noParam', nextPage);
13
15 ApexPages.currentPage().getParameters().put('qp', 'yyyy');
16
19 controller.setLastName('lastname');
20 controller.setFirstName('firstname');
21 controller.setCompany('acme');
22 controller.setEmail('firstlast@acme.com');
23 nextPage = controller.save().getUrl();
24
26 System.assertEquals('/apex/success', nextPage);
27 Lead[] leads = [select id, email from lead where Company = 'acme'];
28 System.assertEquals('firstlast@acme.com', leads[0].email);
29 }
30 }
If you are testing your controller you may see the following error message:
1 Method does not exist or incorrect signature: Test.setCurrentPage(System.PageReference)
If this message appears, look to see if you have created a class called Test. If you have, rename the class.
02 <apex:messages/>
03 <apex:form>
13 </apex:pageBlock>
14 </apex:form>
15 </apex:page>
The ID of a valid account record must be specified as a query parameter in the URL for this page to render. For
example, http://na3.salesforce.com/apex/myValidationPage?id=001x000xxx3Jsxb .
You need to write a custom controller like the following:
01 public class MyController {
02 Account account;
03
05 try{
06 update account;
07 }
08 catch(DmlException ex){
09 ApexPages.addMessages(ex);
10 }
11 return null;
12 }
13
15 return 'MyController';
16 }
17
19 if(account == null)
21 where id = :ApexPages.currentPage().getParameters().get('id')];
22 return account;
23
24 }
25 }
When the user saves the page, if a validation error is triggered, the exception is caught and displayed on the page as
they are for a standard controller.