Newer Version Available
Rewriting URLs for Force.com Sites
Sites provides built-in logic that helps you display user-friendly URLs and links to site visitors. Create rules to rewrite URL requests typed into the address bar, launched from bookmarks, or linked from external websites. You can also create rules to rewrite the URLs for links within site pages. URL rewriting not only makes URLs more descriptive and intuitive for users, it allows search engines to better index your site pages.
For example, let's say that you have a blog site. Without URL rewriting, a blog entry's URL might look like this: http://myblog.force.com/posts?id=003D000000Q0PcN
With URL rewriting, your users can access blog posts by date and title, say, instead of by record ID. The URL for one of your New Year's Eve posts might be: http://myblog.force.com/posts/2009/12/31/auld-lang-syne
You can also rewrite URLs for links shown within a site page. If your New Year's Eve post contained a link to your Valentine's Day post, the link URL might show: http://myblog.force.com/posts/2010/02/14/last-minute-roses
To rewrite URLs for a site, create an Apex class that maps the original URLs to user-friendly URLs, and then add the Apex class to your site.
To learn about the methods in the Site.UrlRewriter interface, see UrlRewriter.
Creating the Apex Class
1global class yourClass implements Site.UrlRewriter {
2 global PageReference mapRequestUrl(PageReference
3 yourFriendlyUrl)
4 global PageReference[] generateUrlFor(PageReference[]
5 yourSalesforceUrls);
6}- Class and Methods Must Be Global
- The Apex class and methods must all be global.
- Class Must Include Both Methods
- The Apex class must implement both the mapRequestUrl and generateUrlFor methods. If you don't want to use one of the methods, simply have it return null.
- Rewriting Only Works for Visualforce Site Pages
- Incoming URL requests can only be mapped to Visualforce pages associated with your site. You can't map to standard pages, images, or other entities.
- To rewrite URLs for links on your site's pages, use the !URLFOR function with the $Page merge variable. For example,
the following links to a Visualforce page named myPage:
1<apex:outputLink value="{!URLFOR($Page.myPage)}"></apex:outputLink> - See the “Functions” appendix of the Visualforce Developer's Guide.
- Encoded URLs
- The URLs you get from using the Site.urlRewriter interface are encoded. If you need to access the unencoded values of your URL, use the urlDecode method of the EncodingUtil Class.
- Restricted Characters
- User-friendly URLs must be distinct from Salesforce URLs. URLs with a three-character entity prefix or a 15- or 18-character ID are not rewritten.
- You can't use periods in your rewritten URLs.
- Restricted Strings
- You can't use the following reserved strings as part of a rewritten
URL path:
- apexcomponent
- apexpages
- ex
- faces
- flash
- flex
- home
- ideas
- images
- img
- javascript
- js
- lumen
- m
- resource
- search
- secur
- services
- servlet
- setup
- sfc
- sfdc_ns
- site
- style
- vote
- widg
- Relative Paths Only
- The PageReference.getUrl() method only returns the part of the URL immediately following the host name or site prefix (if any). For example, if your URL is http://mycompany.force.com/sales/MyPage?id=12345, where “sales” is the site prefix, only /MyPage?id=12345 is returned.
- You can't rewrite the domain or site prefix.
- Unique Paths Only
- You can't map a URL to a directory that has the same name as your site prefix. For example, if your site URL is http://acme.force.com/help, where “help” is the site prefix, you can't point the URL to help/page. The resulting path, http://acme.force.com/help/help/page, would be returned instead as http://acme.force.com/help/page.
- Query in Bulk
- For better performance with page generation, perform tasks in bulk rather than one at a time for the generateUrlFor method.
- Enforce Field Uniqueness
- Make sure the fields you choose for rewriting URLs are unique. Using unique or indexed fields in SOQL for your queries may improve performance.
- You can also use the Site.lookupIdByFieldValue method to look up records by a unique field name and value. The method verifies that the specified field has a unique or external ID; otherwise it returns an error.
- Here is an example, where mynamespace is the namespace, Blog is the custom object name, title is the custom
field name, and myBlog is the value to look for:
1Site.lookupIdByFieldValue(Schema.sObjectType. 2 mynamespace__Blog__c.fields.title__c,'myBlog');
Adding URL Rewriting to a Site
- From Setup, click .
- Click New or click Edit for an existing site.
- On the Site Edit page, choose an Apex class for URL Rewriter Class.
- Click Save.
Code Example
In this example, we have a simple site consisting of two Visualforce pages: mycontact and myaccount. Be sure you have “Read” permission enabled for both before trying the sample. Each page uses the standard controller for its object type. The contact page includes a link to the parent account, plus contact details.
Before implementing rewriting, the address bar and link URLs showed the record ID (a random 15-digit string), illustrated in the “before” figure. Once rewriting was enabled, the address bar and links show more user-friendly rewritten URLs, illustrated in the “after” figure.
The Apex class used to rewrite the URLs for these pages is shown in Example URL Rewriting Apex Class, with detailed comments.
Example Site Pages
This section shows the Visualforce for the account and contact pages used in this example.
1<apex:page standardController="Account">
2 <apex:detail relatedList="false"/>
3</apex:page>1<apex:page standardController="contact">
2 <apex:pageBlock title="Parent Account">
3 <apex:outputLink value="{!URLFOR($Page.mycontact,null,
4 [id=contact.account.id])}">{!contact.account.name}
5 </apex:outputLink>
6 </apex:pageBlock>
7 <apex:detail relatedList="false"/>
8</apex:page>Example URL Rewriting Apex Class
1swfobject.registerObject("clippy.codeblock-5", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17global with sharing class myRewriter implements Site.UrlRewriter {
18
19 //Variables to represent the user-friendly URLs for
20 //account and contact pages
21 String ACCOUNT_PAGE = '/myaccount/';
22 String CONTACT_PAGE = '/mycontact/';
23 //Variables to represent my custom Visualforce pages
24 //that display account and contact information
25 String ACCOUNT_VISUALFORCE_PAGE = '/myaccount?id=';
26 String CONTACT_VISUALFORCE_PAGE = '/mycontact?id=';
27
28 global PageReference mapRequestUrl(PageReference
29 myFriendlyUrl){
30 String url = myFriendlyUrl.getUrl();
31
32 if(url.startsWith(CONTACT_PAGE)){
33 //Extract the name of the contact from the URL
34 //For example: /mycontact/Ryan returns Ryan
35 String name = url.substring(CONTACT_PAGE.length(),
36 url.length());
37
38 //Select the ID of the contact that matches
39 //the name from the URL
40 Contact con = [SELECT Id FROM Contact WHERE Name =:
41 name LIMIT 1];
42
43 //Construct a new page reference in the form
44 //of my Visualforce page
45 return new PageReference(CONTACT_VISUALFORCE_PAGE + con.id);
46 }
47 if(url.startsWith(ACCOUNT_PAGE)){
48 //Extract the name of the account
49 String name = url.substring(ACCOUNT_PAGE.length(),
50 url.length());
51
52 //Query for the ID of an account with this name
53 Account acc = [SELECT Id FROM Account WHERE Name =:name LIMIT 1];
54
55 //Return a page in Visualforce format
56 return new PageReference(ACCOUNT_VISUALFORCE_PAGE + acc.id);
57 }
58 //If the URL isn't in the form of a contact or
59 //account page, continue with the request
60 return null;
61 }
62 global List<PageReference> generateUrlFor(List<PageReference>
63 mySalesforceUrls){
64 //A list of pages to return after all the links
65 //have been evaluated
66 List<PageReference> myFriendlyUrls = new List<PageReference>();
67
68 //a list of all the ids in the urls
69 List<id> accIds = new List<id>();
70
71 // loop through all the urls once, finding all the valid ids
72 for(PageReference mySalesforceUrl : mySalesforceUrls){
73 //Get the URL of the page
74 String url = mySalesforceUrl.getUrl();
75
76 //If this looks like an account page, transform it
77 if(url.startsWith(ACCOUNT_VISUALFORCE_PAGE)){
78 //Extract the ID from the query parameter
79 //and store in a list
80 //for querying later in bulk.
81 String id= url.substring(ACCOUNT_VISUALFORCE_PAGE.length(),
82 url.length());
83 accIds.add(id);
84 }
85 }
86
87 // Get all the account names in bulk
88 List <account> accounts = [SELECT Name FROM Account WHERE Id IN :accIds];
89
90 // make the new urls
91 Integer counter = 0;
92
93 // it is important to go through all the urls again, so that the order
94 // of the urls in the list is maintained.
95 for(PageReference mySalesforceUrl : mySalesforceUrls) {
96
97 //Get the URL of the page
98 String url = mySalesforceUrl.getUrl();
99
100 if(url.startsWith(ACCOUNT_VISUALFORCE_PAGE)){
101 myFriendlyUrls.add(new PageReference(ACCOUNT_PAGE + accounts.get(counter).name));
102 counter++;
103 } else {
104 //If this doesn't start like an account page,
105 //don't do any transformations
106 myFriendlyUrls.add(mySalesforceUrl);
107 }
108 }
109
110 //Return the full list of pages
111 return myFriendlyUrls;
112 }
113
114}Before and After Rewriting
- The original URL for the contact page before rewriting
- The link to the parent account page from the contact page
- The original URL for the link to the account page before rewriting, shown in the browser's status bar
- The rewritten URL for the contact page after rewriting
- The link to the parent account page from the contact page
- The rewritten URL for the link to the account page after rewriting, shown in the browser's status bar