Chapter 2. Custom Components

In this chapter, we will cover the following recipes:

• Passing attributes to components

• Updating attributes in component controllers

• Passing action methods to components

• Data-driven decimal places

• The custom iterator component

• Setting a value into a controller property

• Multiselecting related objects

• Notifying the containing page controller

Introduction

Custom components allow custom Visualforce functionality to be encapsulated as discrete modules, which provides two main benefits:

• Functional decomposition, where a lengthy page is broken down into custom components to make it easier to develop and maintain

• Code re-use, where a custom component provides common functionality that can be re-used across a number of pages

A custom component may have a controller, but unlike Visualforce pages, only custom controllers may be used. A custom component can also take attributes, which can influence the generated markup or set property values in the component's controller.

Custom components do not have any associated security settings; a user with access to a Visualforce page has access to all custom components referenced by the page.

Passing attributes to components

Visualforce pages can pass parameters to components via attributes. A component declares the attributes that it is able to accept, including information about the type and whether the attribute is mandatory or optional. Attributes can be used directly in the component or assigned to properties in the component's controller.

In this recipe we will create a Visualforce page that provides contact edit capability. The page utilizes a custom component that allows the name fields of the contact, Salutation, First Name, and Last Name, to be edited in a three-column page block section. The contact record is passed from the page to the component as an attribute, allowing the component to be re-used in any page that allows editing of contacts.

How to do it…

This recipe does not require any Apex controllers, so we can start with the custom component.

1. Navigate to the Visualforce Components setup page by clicking on Your Name | Setup | Develop | Components.

2. Click on the New...

Updating attributes in component controllers

Updating fields of sObjects passed as attributes to custom components is straightforward, and can be achieved through simple merge syntax statements. This is not so simple when the attribute is a primitive and will be updated by the component controller, as parameters are passed by value, and thus, any changes are made to a copy of the primitive. For example, passing the name field of a contact sObject, rather than the contact sObject itself, would mean that any changes made in the component would not be visible to the containing page.

In this situation, the primitive must be encapsulated inside a containing class. The class instance attribute is still passed by value, so it cannot be updated to point to a different instance, but the properties of the instance can be updated.

In this recipe, we will create a containing class that encapsulates a Date primitive and a Visualforce component that allows the user to enter the date via day/month/year picklists...

Passing action methods to components

A controller action method is usually invoked from the Visualforce page that it is providing the logic for. However, there are times when it is useful to be able to execute a page controller action method directly from a custom component contained within the page. One example is for styling reasons, in order to locate the command button that executes the action method inside the markup generated by the component.

In this recipe we will create a custom component that provides contact edit functionality, including command buttons to save or cancel the edit, and a Visualforce page to contain the component and supply the action methods that are executed when the buttons are clicked.

How to do it…

This recipe does not require any Apex controllers, so we can start with the custom component.

1. Navigate to the Visualforce Components setup page by clicking on Your Name | Setup | Develop | Components.

2. Click on the New button.

3. Enter ContactEdit in the Label field.

4. Accept...

Data-driven decimal places

Attributes passed to custom components from Visualforce pages can be used wherever the merge syntax is legal. The <apex:outputText /> standard component can be used to format numeric and date values, but the formatting is limited to literal values rather than merge fields. In this scenario, an attribute indicating the number of decimal places to display for a numeric value cannot be used directly in the <apex:outputText /> component.

In this recipe we will create a custom component that accepts attributes for a numeric value and the number of decimal places to display for the value. The decimal places attribute determines which optional component is rendered to ensure that the correct number of decimal places is displayed, and the component will also bracket negative values. A Visualforce page will also be created to demonstrate how the component can be used.

How to do it…

This recipe does not require any Apex controllers, so we can start with the custom...

The custom iterator component

The Visualforce standard component <apex:repeat /> iterates a collection of data and outputs the contained markup once for each element in the collection. In the scenario where this is being used to display a table of data, the markup for the table headings appears before the <apex:repeat /> component and is rendered regardless of whether the collection contains any records or not.

Custom iterator components may contain additional markup to be rendered outside the collection, for example, the headings markup in the scenario mentioned earlier. This allows the component to avoid rendering any markup if the collection is empty through the logic implemented in a custom controller.

In this recipe, we will create a custom component that takes a collection of data and renders a containing page block and a page block section for each element in the collection. If the collection is empty, no markup will be rendered. We will also create a containing page that...

Setting a value into a controller property

Visualforce controllers are often re-used across pages with minor variations in behavior specific to the page, for example, displaying accounts of a particular type. While the controller can detect the page that it is being used by and alter its behavior accordingly, this is not a particularly maintainable solution, as use of the controller in any new page would require changes to the Apex code and renaming a page would break the functionality.

A better mechanism is for the page to set the values of properties in the controller to indicate the desired behavior. In this recipe we will create a custom component that takes two attributes: a value and the controller property to set the value into. Two Visualforce pages with a common controller will also be created to demonstrate how the component can be used to change the behavior of the controller to suit the page.

Getting ready

This recipe does not require any Apex controllers, so we can start with the...

Multiselecting related objects

One task that users often find unwieldy when implementing Salesforce is setting up the sObjects to represent many-to-many relationships. A junction object allows a single instance of one sObject type to be related to multiple instances of another sObject type and vice versa.

This requires the user to create a new instance of the junction object and populate master-detail fields to associate two sObjects with each other, resulting in a large number of clicks and page transitions.

In this recipe, we will create a custom object – account group – that acts as a container for multiple accounts. We will then create a page that allows a number of accounts to be associated with a single custom sObject. We will use junction objects for the relationship to allow a single account to be related to multiple account groups, and a single account group to be associated with multiple accounts. A custom Visualforce component will manage the action of presenting the available accounts...

Notifying the containing page controller

In the earlier recipes, we have seen how components can accept an attribute that is a property from the containing page controller and update the value of the property in response to a user action. If the containing page controller needs to determine if the property has changed, it must capture the previous value of the property and compare that with the current value. The same applies if the attribute passed to the component is a field from an sObject managed by the parent page controller.

In this recipe we will create a custom component that can notify its containing page controller when an attribute value is changed. In order to avoid tying the component to a particular page controller class, we will create an interface that defines the method to be used to notify the page controller. This will allow the component controller to notify any page controller that implements the interface.

Note

Interfaces define a "contract" between the calling code and...