A PageReference is a reference to an instantiation of a page. Among other attributes, PageReferences consist of a URL and a set of query parameter names and values.
Use a PageReference object:
·To view or set query string parameters and values for a page
·To navigate the user to a different page as the result of an action method
Refers to a PageReference for a Visualforce page that has already been saved in your organization. By referring to a page in this way, the platform recognizes that this controller or controller extension is dependent on the existence of the specified page and will prevent the page from being deleted while the controller or extension exists.
·PageReference pageRef = new PageReference('partialURL');
Creates a PageReference to any page that is hosted on the Force.com platform. For example, setting 'partialURL' to '/apex/HelloWorld' refers to the Visualforce page located athttp://mySalesforceInstance/apex/HelloWorld. Likewise, setting 'partialURL' to '/' + 'recordID' refers to the detail page for the specified record.
This syntax is less preferable for referencing other Visualforce pages than Page.existingPageName because the PageReference is constructed at runtime, rather than referenced at compile time. Runtime references are not available to the referential integrity system. Consequently, the platform doesn't recognize that this controller or controller extension is dependent on the existence of the specified page and won't issue an error message to prevent user deletion of the page.
§PageReference pageRef = new PageReference('fullURL');
Creates a PageReference for an external URL.
For example:
PageReference pageRef = new PageReference('http://www.google.com');
You can also instantiate a PageReference object for the current page with the currentPage ApexPages method. For example:
PageReference pageRef = ApexPages.currentPage();
Methods
PageReference methods are all called by and operate on a particular instance of a PageReference.
The table below describes the instance methods for PageReference.
Name
Arguments
Return Type
Description
getAnchor
String
Returns the name of the anchor located on the page.
getContent
Blob
Returns the output of the page, as displayed to a user in a Web browser. The content of the returned Blob is dependant on how the page is rendered. If the page is rendered as a PDF, it returns the PDF. If the page is not rendered as a PDF, it returns the HTML. To access the content of the returned HTML as a string, use the toString Blob method.Note
If you use getContent in a test method, a blank PDF is generated when used with aVisualforce page that is supposed to render as PDF.
This method can't be used in:
·Triggers
·Scheduled Apex
§Batch jobs
§Test methods
§Apex email services
If there's an error on the Visualforce page, an ExecutionException is thrown.
getContentAsPDF
Blob
Returns the page as a PDF, regardless of the <apex:page> component's renderAs attribute.
This method can't be used in:
·Triggers
·Scheduled Apex
§Batch jobs
§Test methods
§Apex email services
getCookies
Map<String, System.Cookie[]>
Returns a map of cookie names and cookie objects, where the key is a String of the cookie name and the value contains the list of cookie objects with that name. Used in conjunction with the cookieclass. Only returns cookies with the “apex__” prefix set by the setCookies method.
getHeaders
Map<String, String>
Returns a map of the request headers, where the key string contains the name of the header, and the value string contains the value of the header. This map can be modified and remains in scope for the PageReference object. For instance, you could do:
Returns a map of the query string parameters that are included in the page URL. The key string contains the name of the parameter, while the value string contains the value of the parameter. This map can be modified and remains in scope for the PageReference object. For instance, you could do:
PageReference.getParameters().put('id', myID);
getRedirect
Boolean
Returns the current value of the PageReference object's redirect attribute.
Note that if the URL of the PageReference object is set to a website outside of the salesforce.comdomain, the redirect always occurs, regardless of whether the redirect attribute is set to true orfalse.
getUrl
String
Returns the URL associated with the PageReference when it was originally defined.
setAnchor
String Anchor
System.PageReference
Sets the name of the anchor located on the page.
setCookies
Cookie[] cookies
Void
Creates a list of cookie objects. Used in conjunction with the cookie class.Important
·Cookie names and values set in Apex are URL encoded, that is, characters such as @ are replaced with a percent sign and their hexadecimal representation.
·The setCookies method adds the prefix “apex__” to the cookie names.
§Setting a cookie's value to null sends a cookie with an empty string value instead of setting an expired attribute.
§After you create a cookie, the properties of the cookie can't be changed.
§Be careful when storing sensitive information in cookies. Pages are cached regardless of a cookie value. If you use a cookie value to generate dynamic content, you should disable page caching. For more information, see CachingForce.com Sites Pages.
setRedirect
Boolean redirect
System.PageReference
Sets the value of the PageReference object's redirect attribute. If set to true, a redirect is performed through a client side redirect. This type of redirect performs an HTTP GET request, and flushes the view state, which uses POST. If set to false, the redirect is a server-side forward that preserves the view state if and only if the target page uses the same controller and contains the proper subset of extensions used by the source page.
Note that if the URL of the PageReference object is set to a website outside of the salesforce.comdomain, or to a page with a different controller or controller extension, the redirect always occurs, regardless of whether the redirect attribute is set to true or false.
Request Headers
The following table describes some headers that are set on requests.
Header
Description
Host
The host name requested in the request URL. This header is always set on Force.com Site requests and My Domain requests. This header is optional on other requests when HTTP/1.0 is used instead of HTTP/1.1.
Referer
The URL that is either included or linked to the current request's URL. This header is optional.
User-Agent
The name, version, and extension support of the program that initiated this request, such as a Web browser. This header is optional and can be overridden in most browsers to be a different value. Therefore, this header should not be relied upon.
CipherSuite
If this header exists and has a non-blank value, this means that the request is using HTTPS. Otherwise, the request is using HTTP. The contents of a non-blank value are not defined by this API, and can be changed without notice.
X-Salesforce-SIP
The source IP address of the request. This header is always set on HTTP and HTTPS requests that are initiated outside of Salesforce's data centers.
X-Salesforce-Forwarded-To
The fully qualified domain name of the Salesforce instance that is handling this request. This header is always set on HTTP and HTTPS requests that are initiated outside of Salesforce's data centers.
Example: Retrieving Query String Parameters
The following example shows how to use a PageReference object to retrieve a query string parameter in the current page URL. In this example, the getAccount method references the id query string parameter:
publicclass MyController {
public Account getAccount() {
return [SELECT Id, Name FROM Account
WHERE Id = :ApexPages.currentPage().getParameters().get('Id')];
}
}
The following page markup calls the getAccount method from the controller above:
For this example to render properly, you must associate the Visualforce page with a valid account record in the URL. For example, if 001D000000IRt53 is the account ID, the resulting URL should be:
The getAccount method uses an embedded SOQL query to return the account specified by the id parameter in the URL of the page. To access id, the getAccount method uses the ApexPages namespace:
·First the currentPage method returns the PageReference instance for the current page. PageReference returns a reference to a Visualforce page, including its query string parameters.
·Using the page reference, use the getParameters method to return a map of the specified query string parameter names and values.
§Then a call to the get method specifying id returns the value of the id parameter itself.
Example: Navigating to a New Page as the Result of an Action Method
Any action method in a custom controller or controller extension can return a PageReference object as the result of the method. If the redirect attribute on the PageReference is set to true, the user navigates to the URL specified by the PageReference.
The following example shows how this can be implemented with a save method. In this example, the PageReference returned by the save method redirects the user to the detail page for the account record that was just saved:
publicclass mySecondController {
Account account;
public Account getAccount() {
if(account == null) account = new Account();
return account;
}
public PageReference save() {
// Add the account to the database.
insert account;
// Send the user to the detail page for the new account.
PageReference acctPage = new ApexPages.StandardController(account).view();
acctPage.setRedirect(true);
return acctPage;
}
}
The following page markup calls the save method from the controller above. When a user clicks Save, he or she is redirected to the detail page for the account just created:
