Custom Visualforce Components
Custom components allow you to build a library of reusable user interface elements, encapsulating behavior and appearance while integrating with the data on the page and in the controller using the standard expression language. With custom components, all the functionality of standard components such as pageBlock and inputField is available to you to define from scratch using Visualforce and Apex code.
Custom components can be used to hide the implementation details of client-side technology like JavaScript. For example, a component can wrap a JavaScript user interface library such as Sencha’s Ext JS, freeing Visualforce page developers from the details of integrating Ext JS code into their pages. Custom components can also serve as full-blown pages themselves, reading and writing in the Force.com database through standard or custom controllers.
Defining a Custom Component
To create a new component, select File, New, Visualforce Component in the Force.com IDE. Or, using the Web browser, navigate to App Setup and click Develop, Components.
Custom components are defined with component as the root-level element rather than the familiar page. Following the component tag is an optional set of attribute components specifying the names and types of variables that can be shared between the page and the component. Supported types are primitives, standard and custom database objects, one-dimensional arrays, and custom Apex classes. Attributes can be declared as required, meaning that a page using the component must provide a value or it fails to compile. Attributes can also be assigned to member variables in a controller using the assignTo attribute.
The remainder of the component definition is identical to a standard Visualforce page, containing a combination of JavaScript, CSS, HTML elements, and standard components, as well as other custom components.
Listing 7.13 provides an example of a component for showing an address on a Google Map.
Listing 7.13 Custom Visualforce Component to Render Google Map
<apex:component >
<apex:attribute name="address" type="string" required="true"
description="Address to show on the Google map" />
<apex:includeScript
value="https://maps.googleapis.com/maps/api/js?sensor=false" />
<script>
var geocoder;
var map;
function init() {
geocoder = new google.maps.Geocoder();
var latlng = new google.maps.LatLng(-34.397, 150.644);
var mapOptions = {
zoom: 17,
center: latlng,
mapTypeId: google.maps.MapTypeId.ROADMAP
}
map = new google.maps.Map(document.getElementById("map-canvas"),
mapOptions);
}
function renderAddress(address) {
geocoder.geocode( { 'address': address },
function(results, status) {
if (status == google.maps.GeocoderStatus.OK) {
map.setCenter(results[0].geometry.location);
var marker = new google.maps.Marker({
map: map,
position: results[0].geometry.location
});
} else {
alert("Geocode failed: " + status);
}
});
}
var previousOnload = window.onload;
window.onload = function() {
if (previousOnload) {
previousOnload();
}
init();
renderAddress('{!address}'),
}
</script>
<div id="map-canvas" style="width: 320px; height: 480px;"></div>
</apex:component>
Using a Custom Component
Using a custom component in a page is much like using a standard component. The difference is that instead of prefacing the component with the apex namespace, you use c. Listing 7.14 shows an example of using the custom component defined in Listing 7.13 to render a Google Map for an address. It references the GoogleMap component, followed by a value for its required address attribute containing the street address to render on the map. In this example, the attribute value is hard-coded into the page, but this is not the only way to provide an attribute value. Like standard components, attribute values can include expression language, enabling them to share data with the controller.
Listing 7.14 Visualforce Page Using Custom Component
<apex:page>
<c:GoogleMap address="1 market st. san francisco, ca" />
</apex:page>