Developing Visualforce Pages

Now that you understand the basic architecture of Visualforce, you can jump right into creating Visualforce pages. This section covers creating and modifying pages, and displaying related records.

Creating Your First Page

Visualforce includes a new development method that allows you to immediately see the implementation of your Visualforce pages. This method, referred to as developer mode, is not turned on for all developers by default. To take advantage of this mode, check to make sure that your user profile includes this permission.

1.	Go to Setup Manage Users Users and select your user. Click Edit and make sure the Development Mode permission is selected, then click Save. Development mode gives you the ability to work on your Visualforce pages (as well as controllers) dynamically. Visualforce also includes the ability to create a page on the fly by simply attempting to navigate to the URL for the page. This capability is referred to as a quick fix.
2.	Go to the navigation tool bar of your browser. Edit the URL so that the Force Platform instance is followed by /apex/VisualforcePosition. For example, if the URL of your Force Platform instance is http://na1.salesforce.com, the URL is http://c.na1.visual.force.com/apex/VisualforcePosition. This URL brings up the page shown below. Figure 151. Prompting to create a new Visualforce Page [View full size image]
3.	The quick fix functionality of Visualforce development mode recognizes that no Visualforce page exists with the name VisualforcePosition, so, because you have Development Mode enabled, you are given the opportunity to create the page. Click the Create Page link to create the VisualforcePosition Visualforce page and bring up the page shown below. And yes, congratulations are in order, as you have just created a Visualforce page. The content of the page is less than thrilling, a situation you will change in a matter of minutes. Figure 152. Your first Visualforce Page [View full size image]
2.	Click on the Page Editor link in the footer of the page to change the appearance of the page to the page shown next. Figure 153. Visualforce Page Editor [View full size image]

There are quite a few things to notice in this new page. First of all, you are in development mode, which means that the Visualforce page code is visible in the lower window, with the actual Visualforce page taking up the upper half of the page. The Visualforce code editor includes some standard tools, such as the ability to search for values, including values that satisfy regular expressions, go to a certain line, and undo and redo changes.

Whenever you save your Visualforce code, the save action checks your code to make sure it is valid, flagging the first error it encounters. If the code is valid, the new version is saved and the upper page is refreshed with the new version of the page.

You can also see your first example of Visualforce tags, with the <apex:page> start and end tags. Any Visualforce page must be surrounded by these page tags.

The apex: portion of a Visualforce tag is actually the namespace for the component referenced by the tag. A namespace is a way to qualify the name of a component, insuring that the Visualforce components you will be using in this chapter are all from this standard namespace. Later in this book, you will both create your own component and use Visualforce messaging components, which each have their own namepace.

Finally, you can see that this page includes standard HTML, including the <h1> heading tag. Visualforce pages let you seamlessly use HTML tags with the extended functionality of Visualforce specific tags.

Tip

You can also create or edit Visualforce pages through the Setup Develop Pages menu or through the Force Platform IDE. Accessing Visualforce pages through the Setup menu presents the code as a text file that you can edit in place and save, but without receiving the immediate feedback of development mode. There are three additional features available in these Setup menu Visualforce listing pages that you might find helpful: the ability to clone a page to make a quick copy, access to reports that list where the Visualforce page (or custom component) is used, and what other components the page depends on.

You use Visualforce tags to both specify various components of your page, as well as bind components to matching data fields, data attributes, and functionality available on the Force Platform. As usual, the best way to see exactly what this means is to create a Visualforce page.

3.	Start your editing process by deleting all the code between the <apex:page> tags.
4.	Modify the initial page tag to include the standardController tag, as shown below: <apex:page standardController="Position__c"> This simple attribute connects this Visualforce page with the Position custom object, referenced by the API name of the object, Position__c. This binding also exposes all the actions present in standard controllers, such as save. You will learn about how to override these actions in Chapter 12: Extended Visualforce Components and Controllers. This attribute produces a number of effects in the page. First of all, by default, you can automatically use the same look and feel for the Visualforce page as a standard tab for the object in a regular Force Platform application uses. You do not have to use any extended styling to match this page with your environment, making it easy to integrate Visualforce pages into your standard apps. Secondly, this attribute binds the page to this custom object. You can make easy references to that object, its fields, and the objects that are related to the Position__c object. You can see the power of this binding by adding one component to your Visualforce page.
5.	Position the cursor below the initial page tag. Type in <apex:d As you type in your apex tag, a helper window appears with the tags that match the initial letter, in this example, d, as shown below. Figure 154. Visualforce Page helper [View full size image]
6.	Select the <apex:detail> choice from the helper window to insert the beginning and ending tags into the Visualforce page. Believe it or not, you have just added the only tag you need to completely reproduce the detail page for the Position object.
7.	Click Save to check your code, save the new version and display the page in the window above. The completed code for this version of your Visualforce page is as follows: <apex:page> <apex:detail></apex:detail> </apex:page> That went well, except there is nothing showing in the page above. Well, almost nothing. You can see that the Positions tab is highlighted, which is appropriate behavior for a page bound to the Position object. There is a simple reason why there is no content for the page. You can only show the details for a particular record, and this Visualforce page does not have a particular Position record specified. You can address this by adding a record ID to the URL for the page, but it is easier to just connect this Visualforce page to a button on the detail page for the Position object. This connection automatically passes the unique record ID for the Position record to the Visualforce page.
8.	Go to Setup Create Objects and select the Position object.
9.	Go to the Standard Buttons and Links section, and click the Override link for the View entry, which brings up the Edit page shown in its completed form shown below. The View option executes whenever a user clicks a link to this position, such as the list view shown when the Positions tab is selected, or a link in a related list. By replacing the standard destination with your Visualforce page, you are simply substituting your new page for the default page across your application. Figure 155. Overriding a standard link [View full size image]
10.	Select Visualforce page as the Content Type and the Visualforce Position page you just created from the Content Name picklist. Click Save. Figure 156. Calling your Visualforce Page [View full size image]
11.	Click on the Positions tab and select any position from the list view to bring up the page shown above. This page looks exactly like the default detail page for the selected position, with the exception being that the page comes up in development mode with the Page Editor visible at the bottom of the page. Since you used a simple Visualforce tag that is designed to pick up all the default properties of the page, this outcome is expected. Note When you call a Visualforce page from a standard Force Platform page, the ID for the context record automatically passes to the target page. You can simulate this behavior by adding on the ID for the record to the URL constructed for the page which uses your Force Platform instance. If the record ID for a Position record is a07D0000001Kt7L, your Force Platform instance is na1.salesforce.com, then the URL for the VisualforcePosition page would add /?id=a07D0000001Kt7L to the URL for your instance. You can modify the default behavior by just adding a couple of attributes to the apex:detail tag. The Page Editor has built-in help to guide you to the right attributes for the job.
12.	Enter the Page Editor and click Component Reference on the right. Note You can see a lot of components in this reference. You will be using some of them in this and subsequent chapters, but you should review all the available components to understand the scope and specific capabilities of these components. Select the apex:detail link to bring up a list of attributes for the tag. This help page can also include code samples for the selected component on the Usage tab.
13.	Change the starting apex:detail tag to the following code to eliminate the display of related lists and the title. <apex:detail relatedList="false" title="false">
14.	Save the page to change the display to the page shown below. Figure 157. Your Visualforce page, modified [View full size image]

Visualforce development mode once again brings home one of the key virtues of development as a service. As soon as you save your modified Visualforce code, the results of those changes are immediately visible.

Your first Visualforce page is designed to show you the power of the combination of Visualforce pages and the default functionality provided by the Force Platform. In the next two sections, you modify this initial page to provide a more customized view of the record while still being able to leverage the power provided by the Force Platform.

Modifying Your First Page

It was nice to see how easy it is to create a Visualforce page, but, in the real world, you probably do not want to simply replicate the default page for an object. The apex:detail tag brings in a lot of functionality, but other Visualforce tags give you a finer level of control.

In this section, you create a Visualforce page that still uses the metadata attributes of Force Platform fields, but only displays a small number of fields to present a cleaner interface to your users.

1.	Delete the <apex:detail> tags from your Visualforce page. You will be adding fields to the new version of the page that accept inputs from your users, so the fields will be part of a form. You have to add tags to let the Force Platform environment know that you intend to write data through the page.
2.	Give the initial apex:page an id attribute of "thePage", so that the initial pageBlock tag looks like this: <apex:page standardController="Position__c" id="thePage"> Although you will not be referencing this page directly, you will use the id to help locate a portion of the page you will be adding shortly.
3.	Add <apex:form> tags to the page the same way you added <apex:detail> tags before to begin the redesign process. These tags allow your Visualforce page to send values back to the Force Platform.
4.	Add <apex:pageBlock> tags between the form tags to create an area on the page that inherits the look and feel of standard Force Platform applications from the object identified for the page.
5.	Between the two pageBlock tags, add <apex:pageBlockSection> tags to indicate a section of the larger block. You are now ready to add some individual items to the section.
6.	Using the Apex tag helper, add <apex:inputField> tags within the page block section. Open the Component Reference to see the attribute possibilities for this component. You can see that this component has many more potential attributes than the detail component you used earlier. A lot of these components are used for AJAX-like interaction. The one attribute that does the most initial work for you is the value element. This element is used to identify the particular data field to which the inputField is bound. You use an expression field to form a bidirectional connection between a Force Platform field to a Visualforce page component. The format for this expression is similar to merge field syntax: {!object_name.field_name} It uses the API name for both object and field names.
7.	Change the first inputField by adding the value attribute so that the tag now reads like this: <apex:inputField value="{!Position__c.Department__c}>"
8.	Add another input field to the page block section, with a value of Position__c.Job_Description__c.
9.	Save the new version of the page, changing the displayed Visualforce page to look like the figure which follows below. The code for this version of your Visualforce page is <apex:page standardController="Position__c" id="thePage"> <apex:form> <apex:pageBlock> <apex:pageBlockSection> <apex:inputField value="{!Position__c.Department__c}"> </apex:inputField> <apex:inputField value="{!Position__c.Job_Description__c}"> </apex:inputField> </apex:pageBlockSection> </apex:pageBlock> </apex:form> </apex:page> These few lines of tags have changed the page significantly. You can see that the new page does have input elements, and that the specific types of input elements were derived from the meta-data for the fields: the Department field is shown as a picklist, and the Job Description field is shown as a text area. Both of these fields have the labels and online help that are associated with the fields in the field definition. And these fields are bound to the data in the specified record—the fields contain the current data for this particular record. Since there are only two lonely fields on this page, you might want to stack them in a single column, which can be accomplished with an attribute on the section. Figure 158. New version of your first Visualforce page [View full size image]
10.	Add the attribute columns="1" to the initial pageBlockSection tag. You have no doubt already noticed that all the attribute values are expressed as text values. This requirement makes sense when you realize that this is HTML, which only supports text, not numbers. You have input fields, but no way to interact with the database record that produced the current values. With a couple more tags, you can provide users with a way to summon up standard actions on the record.
11.	Add <apex:pageBlockButton> tags to the page below the initial pageBlock tag, and add the attribute location="bottom" to the initial tag. These tags create an area that holds the buttons you use on your page, with the standard formatting used for Force Platform applications. The location attribute can be top, bottom or both, the default.
12.	Add a set of <apex:commandButton> tags between the pageBlockButton tags. Change the initial tag to: <apex:commandButton action="{!save}" value="Save"> These two attributes call the default save action for the standard controller and assign text to display on the button, respectively. Both actions use the same marker ({! }) to bind the action with an action in the controller for the object. The save action is one of the actions available in all standard controllers. The simple name belies some fairly detailed functionality, which includes running all validations on the saved data, performing either an insert or update action as appropriate, and handling any errors. The cancel action is also standard across standard controllers, simply sending the user back to the previous page without taking any actions on the data submitted with the button click.
13.	Add another command button just below the Save button, with an action and name of Cancel. You should give your users a way to back out of their changes. Whenever your Visualforce page makes a change in Force Platform data, there is a possibility of an error occurring during the save. You should always add a section on your Visualforce page to display any messages produced by errors. Fortunately, Visualforce has a simple component to handle this requirement
14.	Using the helper, add the following tags to your Visualforce page, just below the initial pageBlock tag: <apex:pageMessages></apex:pageMessages> This single component will only appear on the page if messages, such as error messages, are returned to the page. All the remaining Visualforce pages that write data will include a pageMessage component—a good programming practice for you to follow in all your Visualforce pages as well.
15.	Save the page, changing the displayed page to look like the figure below. Figure 159. Adding command buttons [View full size image]
16.	Change the value of the Job Description field and click the new Save button.
17.	Click the Positions tab to return to the list view and see that the value for the field has been changed.

In this section, you have quickly seen the flexibility you can get with Visualforce pages while still using the functionality provided by the data definitions on the Force Platform.

Your next step is to expand the information shown on your page to include related records.

Displaying Related Records

The Force Platform automatically includes lists of related records on the default tabs produced for an object. You can add apex:relatedList tags to include a related list as part of this page.

You still want to show related records on this page, but you would like to control what is shown, other than the default related list display.

1.	Add a new page block section below the current one, and add: <apex:pageBlockTable> tags within the section. The pageBlockTable is one of several tags you can use to iterate over a collection of records. Other built-in tags that will deliver this result are dataTable, which will not pick up the styling of the pageBlock, dataList, which uses the display format of a list, and repeat, which allows you to repeat a group of components. You will learn more about some of these components in this chapter and Chapter 12: Extended Visualforce Components and Controllers.
2.	Edit the initial tag for the page block table to read like this: <apex:pageBlockTable value="{!Position__c.Job_Application__r}" var="JA" title="Job Applications" > The value attribute points to the API name of the relationship that connects the parent Position object with the child Job_Application object. Notice that the relationship has __r (two underscores and the letter “r”), rather than __c. The var attribute assigns a label that the columns of the table use to reference the related object.
3.	Add <apex:column> tags within the page block table.
4.	Modify the initial column tag to: <apex:column value="{!JA.Candidate__c}"> Use the string defined as the var for the page block table to identify the object, and use dot notation to indicate the field in the record.
5.	Add another column to the table, this time with a value of: Candidate_Qualified__c.
6.	Save the Visualforce page code to produce the page shown in below. Figure 160. Visualforce Page with a table of related records [View full size image]

The page shown is highly functional, with the Candidate field automatically providing a link to the detail page for the candidate, just as it would in a standard Force Platform page.

But you might as well take advantage of the flexibility provided by Visualforce pages to offer information that is a little more user friendly, such as providing the first and last names of the candidate, rather than the somewhat cryptic identifier.

7.	Change the value attribute for the first column to: "{!JA.Candidate__r.First_Name__c}". Once again, you are using the name of the relationship from the Job Application object to the Candidate object, so the API name ends with __r.
8.	Add another column to the table to display the last name of the candidate with a value attribute of "{!JA.Candidate__r.Last_Name__c}".
9.	Save the page to produce the new version of the page shown below. Figure 161. Visualforce Page with pageBlockTable [View full size image] The code for this version of your Visualforce page is as follows: <apex:page standardController="Position__c" id="thePage"> <apex:form > <apex:pageBlock> <apex:pageMessages></apex:pageMessages> <apex:pageBlockButtons location="bottom"> <apex:commandButton action="{!save}" value="Save"> </apex:commandButton> <apex:commandButton action="{!cancel}" value="Cancel"> </apex:commandButton> </apex:pageBlockButtons> <apex:pageBlockSection columns="1"> <apex:inputField value="{!Position__c.Department__c}"> </apex:inputField> <apex:inputField value="{!Position__c.Job_Description__c}"> </apex:inputField> </apex:pageBlockSection> </apex:pageBlock> <apex:pageBlock> <apex:pageblockTable value="{!Position__c.Job_Application__r}" var="JA"> <apex:column value="{!JA.Candidate__r.First_Name__c}"> </apex:column> <apex:column value="{!JA.Candidate__r.Last_Name__c}"> </apex:column> <apex:column value="{!JA.Candidate_Qualified__c}"> </apex:column> </apex:pageblockTable> </apex:pageBlock> </apex:form> </apex:page> With only a few more tags, you have gone beyond the capabilities of a standard Force Platform page. You can display fields from a record that is two relationships away from your Position record. The possibilities of Visualforce pages are hopefully starting to open up before you. But there is more to come in the remaining sections of this chapter.

Using Links to Standard Force Platform Pages

You have already seen the use of a command button to call the standard Force Platform save function for the Position record. You can do even more with buttons and links on your Visualforce page.

In an earlier version of this Visualforce page, the Name field for the Job Application was displayed as a link to the detail page for the record. In this section, you learn how to implement the same functionality through the more user-friendly combination of first and last name and another Visualforce component, without having to use the Name field.

1.	Return to the Page Editor. Delete the first two columns for the pageBlocktable.
2.	Add <apex:column> tags to the table. Add the attribute headerValue="Candidate" to place the proper title over the column which will act as a link to the candidate. Add <apex:outputLink> tags between the initial and final column tags. The outputLink is a Visualforce component that generates a link in the Visualforce page.
3.	Add the following code between the two outputLink tags to display the first and last names of all related candidates in the table: {!JA.Candidate__r.First_Name__c} {!JA.Candidate__r.Last_Name__c} Notice that you can use these expressions within the standard display areas of a Visualforce page. Figure 162. outputLinks in place [View full size image]
4.	Save your page to see the new display, as shown in the figure above. Now add an action for the link. You want to use this link to call the standard Force Platform page for viewing information about the candidate. To accomplish this task, you need to use the URLFOR() function and a global Force Platform variable to point to the page. The URLFOR() function has two required parameters—an identifier for the target page and a value for the ID used for the page. You can already guess how to represent the ID value in this table: with the JA.Candidate__r.ID, which contains to the ID of the related Candidate record. You can reference the destination page with the global $Action variable. To represent the page used to view the Candidate__C object, the syntax is: $Action.Candidate__c.View. Other actions available include New and Edit. The last step is to add this formula as the value attribute of the outputLink, whose initial tag now looks like this: <apex:outputLink value="{!URLFOR($Action.Candidate__c.View, JA.Candidate__r.ID)}">
5.	Edit the initial outputLink tag to include the value attribute code and save your code. The code for this version of your Visualforce page is: <apex:page standardController="Position__c" id="thePage"> <apex:form > <apex:pageBlock> <apex:pageMessages></apex:pageMessages> <apex:pageBlockButtons location="bottom"> <apex:commandButton action="{!save}" value="Save"> </apex:commandButton> <apex:commandButton action="{!cancel}" value="Cancel"> </apex:commandButton> </apex:pageBlockButtons> <apex:pageBlockSection columns="1"> <apex:inputField value="{!Position__c.Department__c}"> </apex:inputField> <apex:inputField value="{!Position__c.Job_Description__c}"> </apex:inputField> </apex:pageBlockSection> </apex:pageBlock> <apex:pageBlock > <apex:pageblockTable value="{!Position__c.Job_Application__r}" var="JA"> <apex:column headerValue="Candidate"> <apex:outputLink value="{!URLFOR($Action.Candidate__c.View, JA.Candidate__r.ID)}"> {!JA.Candidate__r.First_Name__c} {!JA.Candidate__r.Last_Name__c} </apex:outputLink> </apex:column > <apex:column value="{!JA.Candidate_Qualified__c}"> </apex:column> </apex:pageblockTable> </apex:pageBlock> </apex:form> </apex:page>
6.	Click the link for any of the candidates to take you directly to the detail page.

With these slight modifications, you can integrate all the standard functionality of your Force Platform pages into your Visualforce page. This ability means that you can use Visualforce to supplement your standard applications, rather than replace every page with a new alternative Visualforce page.

The functionality works just fine, but your users will still find themselves navigating to a completely different page to view detailed information for a related candidate. Isn’t there some way to show that information on the same Visualforce page? You bet.