Custom Components in Salesforce:

Similar to the way you can encapsulate a piece of code in a method and then reuse that method several times in a program, you can encapsulate a common design pattern in a custom component and then reuse that component several times in one or more Visualforce pages.

For example, suppose you want to create a photo album using Visualforce pages. Each photo in the album has its own border color, and a text caption that displays beneath it. Rather than repeating the Visualforce markup required for displaying every photo in the album, you can define a custom component named singlePhoto that has attributes for image, border color, and caption, and then uses those attributes to display the image on the page. Once defined, every Visualforce page in your organization can leverage the singlePhoto custom component in the same way as a page can leverage standard components such as <apex:dataTable> or <apex:relatedList>.

Defining Custom Components

To define a custom component for use in a Visualforce page:

1. In Salesforce from Setup, enter Components in the Quick Find box, then select VisualforceComponents.
2. Click New.
3. In the Label text box, enter the text that should be used to identify the custom component in Setup tools.
4. In the Name text box, enter the text that should identify this custom component in Visualforce markup. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
5. In the Description text box, enter a text description of the custom component. This description appears in the component reference with other standard component descriptions as soon as you click Save.
6. In the Body text box, enter Visualforce markup for the custom component definition. A single component can hold up to 1 MB of text, or approximately 1,000,000 characters.
7. Click Version Settings to specify the version of Visualforce and the API used with this component. You can also specify versions for any managed packages installed in your organization.
8. Click Save to save your changes and view the custom component’s detail screen, or click Quick Save to save your changes and continue editing your component. Your Visualforce markup must be valid before you can save your component.

Custom Component Markup

All markup for a custom component is defined within an <apex:component> tag. This tag must be the top-level tag in a custom component definition. For example:

1	<apex:component>

2

<b>

3	<apex:outputText value="This is my custom component."/>

4

</b>

5	</apex:component>

Notice that the markup can be a combination of Visualforce and HTML tags, just like other Visualforce pages.

For a more complex example, you could use a custom component to create a form that is used across multiple Visualforce pages. Create a new custom component named recordDisplay and copy the following code:

1	<apex:component>

2	<apex:attribute name="record" description="The type of record we are viewing."

3	type="Object" required="true"/>

4

5	<apex:pageBlock title="Viewing {!record}">

6	<apex:detail />

7	</apex:pageBlock>

8	</apex:component>

Next, create a page called displayRecords and use the following code:

1	<apex:page >

2	<c:recordDisplay record="Account" />

3	</apex:page>

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:

1	https://Salesforce_instance/apex/displayRecords?id=001D000000IRt53

You should see a page with details about the account you passed in as an ID.

Now, replace the code in displayRecords with the following sample:

1	<apex:page>

2	<c:recordDisplay record="Contact" />

3	</apex:page>

Again, pass in the ID of a contact before refreshing the page. You should see the page display information about your Contact.

Custom Component Attributes contains more information on using the <apex:attribute> component.

Using Custom Components in a Visualforce Page

The body of an <apex:component> tag is the markup that is added to a standard Visualforce page whenever the component is included. For example, the following Visualforce page uses the component defined in Custom Component Markup (in this example, the component was saved with the name myComponent):

1	<apex:page standardController="Account">

2	This is my <i>page</i>. <br/>

3	<c:myComponent/>

4	</apex:page>

It results in the following output:

1	This is my page.

2	This is my custom component.

To use a custom component in a Visualforce page you must prefix the component's name with the namespace in which the component was defined. For example, if a component named myComponent is defined in a namespace called myNS, the component can be referenced in a Visualforce page as <myNS:myComponent>.

For ease of use, a component that is defined in the same namespace as an associated page can also use the c namespace prefix. Consequently, if the page and component from the sample above are defined in the same namespace, you can reference the component as <c:myComponent>.

If you want to insert content into a custom component, use the <apex:componentBody> tag.

Custom Component Attributes

Apart from standard Visualforce markup, the body of an <apex:component> tag can also specify the attributes that can be passed in to the custom component when it’s used in a Visualforce page. The values of such attributes can then be used directly in the component, or within the component’s controller, if applicable. They can’t, however, be used in the constructor of the component’s controller.

Attributes are defined with the <apex:attribute> tag. For example, the following custom component definition specifies two required attributes named value and borderColor. Values for these attributes are referenced in the custom component definition using standard {! } Visualforce expression language syntax:

01	<apex:component>

02	<!-- Attribute Definitions -->

03	<apex:attribute name="myValue" description="This is the value for the component."

04	type="String" required="true"/>

05	<apex:attribute name="borderColor" description="This is color for the border."

06	type="String" required="true"/>

07

08	<!-- Component Definition -->

09	<h1 style="border:{!borderColor};"/>

10	<apex:outputText value="{!myValue}"/>

11

</h1>

12	</apex:component>

Use this component in a Visualforce page with the following markup:

1	<c:myComponent myValue="My value" borderColor="red"/>

An <apex:attribute> tag requires values for the name, description, and type attributes:

• The name attribute defines how the custom attribute can be referenced in Visualforce pages. names for attributes must be unique within a component.
• The description attribute defines the help text for the attribute that appears in the component reference library once the custom component has been saved. The custom component is listed in the reference library with the standard components that are also available.
• The type attribute defines the Apex data type of the attribute. Only the following data types are allowed as values for the type attribute:
  • Primitives, such as String, Integer, or Boolean.
  • sObjects, such as Account, My_Custom_Object__c, or the generic sObject type.
  • One-dimensional lists, specified using array-notation, such as String[], or Contact[].
  • Maps, specified using type="map". You don’t need to specify the map’s specific data type.
  • Custom Apex classes.

For information on additional <apex:attribute> attributes, see apex:attribute.

Default Custom Component Attributes

Two attributes are always generated for custom components. These attributes don’t need to be included in your component definition:

id

An identifier that allows the custom component to be referenced by other components in the page. If not specified, a unique identifier is generated automatically.

rendered

A Boolean value that specifies whether the custom component is rendered on the page. If not specified, this value defaults to true.

Custom Component Controllers

Similar to standard Visualforce pages, custom components can be associated with a controller written in Apex. This association is made by setting the controller attribute on the component to your custom controller. You can use the controller to perform additional logic before returning the component's markup to the associated page.

Accessing Custom Component Attributes in a Controller

To access the value of a custom component attribute in an associated custom component controller:

1. Define a property in the custom component controller to store the value of the attribute.
2. Define a getter and setter method for the property. For example:

   01	public class myComponentController {

   02

   03	public String controllerValue;

   04

   05	public void setControllerValue (String s) {

   06	controllerValue = s.toUpperCase();

   07

   }

   08

   09	public String getControllerValue() {

   10	return controllerValue;

   11

   }

   12

   }

   Notice that the setter modifies the value.
3. In the <apex:attribute> tag in your component definition, use the assignTo attribute to bind the attribute to the class variable you just defined. For example:

   01	<apex:component controller="myComponentController">

   02	<apex:attribute name="componentValue" description="Attribute on the component."

   03	type="String" required="required" assignTo="{!controllerValue}"/>

   04	<apex:pageBlock title="My Custom Component">

   05

   <p>

   06	<code>componentValue</code> is "{!componentValue}"

   07

   <br/>

   08	<code>controllerValue</code> is "{!controllerValue}"

   09

   </p>

   10	</apex:pageBlock>

   11	Notice that the controllerValue has been upper cased using an Apex method.

   12	</apex:component>

   Note that when using the assignTo attribute, getter and setter methods, or a property with get and set values, must be defined.
4. Add the component to a page. For example,

   1	<apex:page>

   2	<c:simpleComponent componentValue="Hi there, {!$User.FirstName}"/>

   3	</apex:page>

The output of the page will look something like the following:Notice that the Apex controller method changes controllerValue so that it is displayed with uppercase characters.

What is an attribute tag? What is the syntax for including them?

An attribute tag is a definition of an attribute of a custom component and it can only be a child of a component tag.

Note that you cannot define attributes with names like id or rendered. These attributes are automatically created for all custom component definitions. 

1 2 3 4 5 6 7 8 9

<apex:component>  <apex:attribute name="myValue" description="This is the value for the component." type="String" required="true"/>  <apex:attribute name="borderColor" description="This is color for the border." type="String" required="true"/>    <h1 style="border:{!borderColor}">  <apex:outputText value="{!myValue}"/>  </h1> </apex:component>