There will be occasions when out-of-the-box components do not match specific use-case requirements, in which case it is necessary to create custom components, either by extending existing components, or by creating completely new components. This examples page demonstrates how to create a custom component with AJAX functionality using the JSF Edition.

Prerequisites and Intended Audience

Software

To run the example, the following software is required:

• Backbase Enterprise Ajax 4.1.0 - JSF Edition (and higher)
• JDK
• Tomcat 5.5
• Eclipse IDE with the JSF Edition plugin installed

Before starting the example, use the Backbase Eclipse plugin to create an empty JSF Edition Project.

Competencies

Experience to the indicated level is required with the following technologies:

• Beginner Java
• Beginner Backbase widget development
• Beginner Backbase JSF component development
• Intermediate Backbase TDL

Resources

The rectangular-balloon.xml file provides the starting point for the example. The file contains TDL code that defines a custom widget created for this example. This widget allows you to show a rectangular edged balloon in your application. For more information about TDL, please refer to the Client Framework Application Development Guide and API Reference listed in the Additional Resources.

The source code for the base widget extended from the b:balloonBase widgets is available at rectangular-balloon.xml.

Overview

Although a broad range of feature-rich components are bundled with the JSF Edition, there may be circumstances in which the functionality required for a component in an application is not available out-of-the-box. In this case, you have the option either to extend an existing component or to create a completely new one. When you create or extend a component, you may also need to create a new widget that encapsulates the client-side functionality of the component.

For this example, a custom widget is provided that changes the representation of a balloon widget from having rounded corners (the default) to having square corners.

In this example, particular attention is paid to the procedure for creating a component that belongs to a custom taglib URI.

Component Design

Designing a custom component requires consideration of both the server-side component implementation as well as the client-side implementation. For Backbase JavaServer Faces components, the client-side functionality of the component is encapsulated in a client widget. In this example, the b:balloonBase widget in the http://www.backbase.com/2006/btl namespace is extended, and a new rectangularBalloon widget is created in the http://www.backbase.com/2007/custom/balloon namespace. The design requires that the taglib URI for the JavaServer Faces custom component is completely different to that of the aforementioned widget, otherwise there will be conflicts with existing components that are already defined in the same taglib. The design is depicted in the following figure:

Figure: custom component design.

Client Side Functionality

As already mentioned, to create the rectangularBalloon, the example extends balloonBase rather than the balloon element. The base class defines widget functionality, and contains no template definition. To create the rectangularBalloon, because the intention is to change the representation of the default widget, it is more efficient to extend from balloonBase rather than balloon. For better understanding please refer to the Client Framework Technical Overview and API Reference listed in the Additional Resources or examine the balloonBase.xml file located in the JSF Edition installation folder.

Note: for information about the criteria that will determine whether to extend an abstract base element class or an existing client widget, please refer to the Client Framework Widget Development Guide listed in the Additional Resources.

To define the custom namespace for the widget, the name attribute of the <d:namespace> tag that wraps the TDL definition is set to "http://www.backbase.com/2007/custom/balloon".

Listing: setting the namespace for the rectangularBalloon custom widget.

The TDL template to implement the rectangularBalloon custom widget is shown in the following listing:

Listing: rectangularBalloon TDL template definition.

The resulting widget (square corners) is compared with the out-of-the-box widget (rounded corners) in the following figure:

Figure: comparison of out-of-the-box and custom balloon widgets.

Creating the JSF Component

The Eclipse IDE Create Component Wizard will be used to create the new component. This wizard generates JSF Edition code that defines a custom component, including the component class, renderer class, tag class, TDL file, and faces-config.xml file.

In the Eclipse IDE, before creating the new component with wizard, first create the com.backbase.custom.component package used for this example. Then right click the package in the Eclipse IDE Package Explorer view, and from the context menu, choose Backbase>Generate JSF Component to start the Create Component Wizard. Creating a component with the wizard is a four-step procedure.

Note: for a complete description of the wizard, please refer to the JSF Edition Component Development Guide listed in the Additional Resources.

In the Define Component and Render step of the wizard, all fields are completed with default values automatically set for your component. For detailed information about the different fields, please refer to the JSF Edition Component Development Guide.

This example extends the existing Backbase balloon component (UIBackbaseBalloon.java located in the com.backbase.bjsf.component.btl package). All the component classes in this example will packaged in com.backbase.custom.component. A user-defined http://www.backbase.com/2007/custom/balloon/jsf taglib URI will also be specified for our component.

To create the custom component, use the settings shown in the following figure:

Figure: component and renderer definition using the Create Component Wizard.

Note: when creating a new component, the base classes that are available to be extended are displayed in the Base Class drop-down list. You can use any of them. In addition to this, you can also use any other Component Class. In our case, we used the UIBackbaseBalloon Component Class under com.backbase.bjsf.component.btl package.

The subsequent wizard step provides various options that depend on the component behavior. For this example, the default settings are adequate.

In the Enter field values step, you have option to map any client attribute by adding new fields for each. The wizard will create appropriate server side codes for every field you defined. Additionally, your mapping will be rendered in the client side if you check Render as true. And checking Client Sync as true will enable the synchronization of values according to the value synchronization mechanism of the JSF Edition. For this example, define an attribute to set the direction of the balloon by mapping the mode attribute, as shown in the figure:

Figure: component field definition using the create component wizard.

The client mode attribute mapped in this example defines the relative location of the balloon pop-up. The supported settings for this attribute are top-left, top-right, bottom-left, and bottom-right. Notice that the new component attribute is named balloonMode, and not mode. This is because there is already a built-in mode attribute coming from the base classes for this component. If the name of a built-in attribute is used, the new attribute will override the built-in attribute due to the inheritance, resulting in unpredictable component behavior.

Note: avoid setting same attribute name for your component that comes from the component base classes while mapping custom widget attributes, otherwise the built-in attributes will be overridden. For more information about built-in attributes by checking Backbase JavaServer Faces API documentation.

The last wizard step includes an option to specify the taglib URI for the component. For this example, the URI is http://www.backbase.com/2007/custom/balloon/jsf. In a JSP, the taglib URI is mapped to a unique prefix that must be included as part of the tag to instantiate the component.

Figure: Defining the directory location, file names and taglib URI in the final wizard step.

After completing the wizard, the necessary Java files and taglib file are generated, and the web.xml and faces-config.xml files are updated accordingly.

To use your custom component:

• Declare the taglib in the JSP.
• Include the resource files containing the Client functionalities of the component (namely the widget definition file) using xi:include.
• Add the tag.

An example that uses the custom component is shown in the following listing:

Listing: implementing the custom component in the web application.

Live Demo

This example has demonstrated how to create a custom JSF Edition component with a user-defined taglib URI. The Eclipse wizard delivered with the JSF Edition simplifies the component creation process, allowing for rapid and effective development of JSF Edition components.

In the following live demo, the functionality implemented in the preceding steps is shown:

Additional Resources

For more information, please refer to the following documentation, examples and reference material:

• WAR version of this examples page available for download at Custom Component Creation WAR (WAR)
• JSF Edition Component Development Guide (PDF)
• JSF Edition Online Javadoc (download) (zip)
• Client Framework Application Development Guide (PDF)
• Client Framework Technical Overview (PDF)
• Client Framework Widget Development Guide (PDF)
• Client Framework Online Reference (download) (zip)