Configuring the Faces Library Definition
A Faces Library Definition contains project resources needed for a component library and the metatdata necessary for the interpretation of JSF tags.
Add support for an existing component library.
To configure the Faces Library Definition:
- Double-click your Faces Library Definition to open the library definition file in the editor. Your library definition file has a JLD extension.
- Once you have configured your library definition, save the file. The definition is updated.
- To update the file, click
Update Library Definition then click
Perform update. The update process finds new tags and attributes in the tag library and adds them to the library definition.
Remember: Increment the library definition version after the update is complete.
Faces Library Definition
The Faces Library Definition editor is used to configure the details about how to incorporate a new JSF library into the project.
- Library name
- Name of the library.
- Description
- A description of the library.
- Taglib URI
- Lists additional taglibs that the library requires at runtime.
- Prefix
- The prefix given to the tags.
- Minimum JSF level
- Minimum level of the JSF specification required by the library.
- Version
- The version number indicates the level of the configuration in the library definition. It signals when newer resources may be available to existing Web applications. When a library definition is initially created, pick a version that is meaningful for the selected tag library. For example, start with the release number for publicly-available tag libraries. The typical form of the version number is a dot-separated string such as 1.2.3.4. Once the library definition is in use and the resources for a tag library are installed in one or more Web applications, further changes to the definition may need a version update. If any changes are made in the
Application Configuration section of a deployed library definition, the version number should be increased. This will indicate to the workbench that newer resources or configuration changes are available and any Web projects that use the tag library will be marked with an error. The Quick Fix associated with that error can update the Web projects with the current configuration. For more information on the resource update, refer to Updating Faces runtime resources for Web projects.
Remember: If a tag library has not yet been added to a Web project, increasing the version number is unnecessary. Changes to any areas of the Library Definition other than the Application Configuration section are dynamically read and therefore do not require a version change.
Application Configuration
This section details how the Dynamic Web project should be set up to use the new component library. The configuration declares how to copy files into the Web project as well as any configuration changes that must be made to make components function properly
- Taglib Dependencies
- This page specifies what other JSF tag libraries are required in order for this library to function properly. When a library is installed in a Web project, the tool will automatically ensure the dependent libraries are also installed. The two JSF taglibs that are included in any JSF implementation will always be selected by default.
- Resources
- The resources area is used to define files to copy into a Dynamic Web project when a library is first used. The source path is the relative path to a file within the Faces Definitions project. The target path is the path within the project where the library is used. For example, the file from source path
/mystylesheet.css might be given a target of
/theme and would result in a copy of the CSS file being placed into the
/theme folder of the Web project.
- web.xml Updates
- This section may contain information about several types of modifications that will be made to the deployment descriptor of a Dynamic Web project where the Faces library is used. New servlets, context parameters, and filters can be configured under corresponding subsections in the editor.
- Faces Configuration File
- If a new library requires configuration in faces-config.xml to function properly, it is specified in this section. The parameter source path is a relative path to a valid faces configuration file in the Faces Definitions project.
Important: This file is copied to a Dynamic Web project when needed and referenced through a JSF context parameter in web.xml. Therefore the source file should not be called faces-config.xml or accidental overwrites may occur.
Tag Library
This section lists all the custom tags that make up the library and enables the configuration of many details regarding tool behavior. For example, you can specify the appearance of tags in the Palette, behaviors when dropping tags onto the editor, the visual appearance of components in the JSP, and various details about tag attributes and data binding.
This section of the editor is used to configure details about the actual tags in the component library. When the library definition is generated it will contain all the tags found in the given TLD, but the order of tags may be modified with the
Up and
Down buttons in the left-hand pane. The desired tag ordering will be reflected in the library's appearance in the Palette.
Some visual information about the library's palette category can be configured on this page. Any stylesheet links or JavaScript™ references that apply to all tags in a library should also be configured here. At the time a tag is added from the palette, the corresponding <link> and <script> tags will be added to the JSP.
- Tag
- This page configures the appearance of the component tag in the palette, including icon and label information. The tag can also be hidden by default or completely removed from the palette choices.
- Drop properties
- The behavior of inserting new tags from the palette is modified by parameters on this page. If a component requires a JSF form tag, the form is automatically added or repositioned in the JSP. If the component is a container-like control and other components are allowed as children, select
Allows children. Stylesheet links and JavaScript references can be specified on a tag-by-tag basis on this page. Stylesheet and JavaScript specifications can also be made for the entire library on the Tag page.
- Default tag attributes
- To set a default attribute value of a tag, specify the name and value of the attribute. When a component tag is added from the palette this attribute value is automatically set.
- Visualization
- For many Faces components, the display of the tag in the visual page editor renders correctly. In some cases however the tag rendering fails entirely or it does not render appropriately. If the rendering fails, the tag appears as a gray box with the tag name. When this occurs you can customize the appearance of the tag by specifying basic HTML tags with some variable modifiers. This tag is used as a substitute visualization inside the page editor.
- Tag attributes
- For each tag, an attribute description and type can be specified. The order of the attributes in the list and the type for each will affect how they are shown and edited in the Properties view. Certain types indicate a set of available choices or a specific helper dialog to assist in setting an attribute value.
- Data binding
- This section enables you to configure the binding behavior when data from the Page Data view is bound to a Faces component. The library definition indicates if a tag expects a collection of data rather than a single object. If you are binding data to a tag you need to set an attribute other than
value that can be defined as the
Main binding attribute. For iterative tags that use a tag attribute to indicate their children values, for example, the
var attribute of a dataTable, that attribute should be specified and will be used when binding child tags.
- Child tags
- When a Child Tags template is defined it will appear as an option on the Properties View for the associated tag. Selecting it will generate new component tags and insert them inside the selected control. For example, a data table tag may use a Child Tags template to create a new column.
Data Templates
This optional section holds templates that can be used to generate new component tags when you drop data from the Page Data view onto a Web page.
Data templates are used to generate new Faces component tags when inserting data into a page from Page Data view. A library definition should only contain templates for tags from the current library.
The two available template types are nested inside each other to build up complex controls. An iterative template generates a tag for containing multiple data items, for example, dataTable and multiple child tags to enclose each individual data item, for example, column. Property templates define the tag that is generated for a single data item, for example, outputText.
- Property template
- A property template creates a tag bound to a single data item in Page Data view, for example, an output text control bound to a string.
- Iterative template
- Iterative templates determine how a component will access and display data on a page. These templates determine how both the wrapper and iterative components will iterate over data. Wrapper templates enclose iterative templates, which enclose property (data) templates. Specify the name, class, wrapper pattern, and iterative pattern for the template. An iterative template nests inside a single wrapper template and encloses each property template. For example, a wrapper template could be defined for a Data Table tag, and a corresponding iterative template could be defined for a Column tag.