How to Configure Searching in a Hierarchy Viewer

30 Creating Custom ADF Faces Components 30-1 30 Creating Custom ADF Faces Components This chapter describes how to create custom ADF Faces rich client components. This chapter includes the following sections: ■ Section 30.1, Introduction to Custom ADF Faces Components ■ Section 30.2, Setting Up the Workspace and Starter Files ■ Section 30.3, Client-Side Development ■ Section 30.4, Server-Side Development ■ Section 30.5, Deploying a Component Library ■ Section 30.6, Adding the Custom Component to an Application

30.1 Introduction to Custom ADF Faces Components

The ADF Faces component library provides a comprehensive set of UI components that covers most of your requirements. However, there are situations when you will want to create a custom rich component that is specific to your application. A custom rich component will allow you to have custom behavior and perform actions that best suit the needs of your application. JSF technology is built to allow self-registering components and other framework parts. The core JSF runtime at web application startup accomplishes this by inspecting all JAR files in the class path. Any JAR files whose META-INFfaces-config.xml file contains JSF artifacts will be loaded. Therefore, you can package custom ADF Faces components in a JAR file and simply add it into the web project. For each ADF Faces component, there is a server-side component and there can also be a client-side component. On the server, for JSPs, a render kit provides a base to balance the complex mixture of markup language and JavaScript. The server-side framework also adds a custom lifecycle to take advantage of the API hooks for partial page component rendering. On the client, ADF Faces provides a structured JavaScript framework for handling various nontrivial tasks. These tasks include state synchronization using partial page rendering. For more information about the ADF Faces architecture, see Chapter 3, Using ADF Faces Architecture. Note: Creating custom standard JSF components is covered in many books, articles, web sites, and the JavaServer Faces specification, therefore, it is not covered in this guide. This chapter is intended to describe how to create ADF Faces components. 30-2 Web User Interface Developers Guide for Oracle Application Development Framework ADF Faces components are derived from the Apache MyFaces Trinidad component library. Because of this, many of the classes you extend when creating a custom ADF Faces component are actually MyFaces Trinidad classes. For more information about the history of ADF Faces, including its evolution, see Chapter 1, Introduction to ADF Faces Rich Client. Between the JSP and the JSF components is the Application class. The tag library uses a factory method on the application object to instantiate a concrete component instance using the mnemonic referred to as the componentType. A component can render its own markup but this is not considered to be a best practice. The preferred approach is to define a render kit that focuses on a strategy for rendering the presentation. The component uses a factory method on the render kit to get the renderer associated with the particular component. If the component is consumed in an application that uses Facelets, then a component handler creates the component. In addition to functionality, any custom component you create must use an ADF Faces skin to be able to be displayed properly with other ADF Faces components. To use a skin, you must create and register the skinning keys and properties for your component. This chapter describes only how to create and register skins for custom components. For more information about how skins are used and created in general, see Chapter 20, Customizing the Appearance Using Styles and Skins.

30.1.1 Developing a Custom Component with JDeveloper

An ADF Faces component consists of both client-side and server-side resources. On the client side, there is the client component, the component peer the component presenter, and any events associated with the client component. On the server side, there is the server component, server component events, and event listeners. Also, there is a component renderer, a component JSP tag, a composite resource loader, a JavaScript resource loader, and a resource bundle. The component also has several configuration and support files. Together, these classes, JavaScripts, and configuration files are packaged into a JAR file, which can be imported as a library into an application and used like other components. You can use JDeveloper to set up the application workspace and project in which you develop the custom component. After you have created the workspace and project, you add starter working files for the required classes, JavaScript files, and configuration files that make up the custom component. During development, you edit and add code to each of these files, specific for the custom component. The development process is as follows:

1. Create an application, workspace, and project as an environment for development.

This includes adding library dependencies and registering XML schemas. You should not create the component in the same application in which you plan to use the component.

2. Create a deployment profile for packaging the component into a JAR file.

3. Create the following starter configuration and support files:

Tip: To work with ADF Faces components, your custom component must use at least the ADF Faces simple skin, because the FusionFX, blafplus-rich, and blafplus-medium skins inherit from the simple skin. Additionally, if there is any chance your component will be used in an Oracle WebCenter application, then your skin must also be registered with the simple.portlet skin.