Configuring the Faces Library Definition

Library name

Name of the library.

Description

A description of the library.

Taglib URI

The taglib URI of the component library.

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.

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 Web project when a library is first used. To add a resource file, right-click Resources and then select Add > File.

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 Web project where the Faces library is used. New servlets, context parameters, and filters can be configured under corresponding subsections in the editor.

To add a servlet, context parameter, or filter:

1. Select web.xml.
2. Click Add and then select the item from the dialog.

Servlet

This page defines parameters for a new servlet to be added to web.xml.

Context parameter

This section records the details for adding a new context parameter in the Web deployment descriptor. At the time the Faces library is first used in a Web project, web.xml will be modified to include this information.

Filter

This section defines a new filter which will be added into web.xml. Initialization parameters for this filter are added by clicking Add in the left-hand pane of the editor.

Initialization parameter

This page collects data for an initialization parameter for a web.xml filter definition.

URL Mappings

This section collects any URL-based mappings for the filter.

Servlet Mappings

This section collects filter mappings based on a servlet name which is defined elsewhere in web.xml.

To add a filter:

1. Select Filter.
2. Click Add and then select the item from the filter type from the dialog.

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 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.

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.

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, select Requires form. The form is automatically added or repositioned in the page. If the component is a container-like control and other components are allowed as children, select Allows children. Stylesheet links, JavaScript references, and allowed facets 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.

Sample visualization templates are available and include examples of how to use the variable modifiers. To view the templates, click Edit in the Details section.

Learn more about visualization pattern variables

A visualization pattern is used for controlling the appearance of a component in the design pane of the page editor. The pattern consists of HTML markup and some optional substitution variables to dynamically alter the content of the visualization. When a component is dragged onto a page, the corresponding pattern is evaluated and the page editor uses the resulting HTML to create a useful design-time representation. Details of the available pattern variables are shown in Table 1.

Table 1. Visualization pattern variables

Variable	Description	Example
${children}	The ${children} variable emits all the child tags of the tag being visualized, if any are present, at the position of the ${children} variable in the pattern. The children tags are inserted in the order they appear in the original page, and the page editor will also compute their visualizations since the child tags can also use patterns. Since all child tags are inserted in the same location there can only be one use of the ${children} variable in a pattern.	<div> ${children} </div>
${children:row}	The row modifier of the ${children} variable emits the children tags in a sequence of HTML table cell <td> elements. Use this variable when you are arranging multiple components horizontally.	<table> <tr> ${children:row} </tr> </table>
${children:grid(param[,param]*)}	The grid modifier creates a set of HTML table rows and cells that contain children of a tag. Children are added left-to-right and wrap to the next row when a specified number of columns is reached. The default column count is 2. The optional comma-separated parameter list overrides the number of columns in the grid. The parameter options are: attr.attrName The value of the tag attribute with the name attrName. This must resolve to an integer. N A positive integer constant. Parameters are examined sequentially until a valid value is found. For example the pattern ${children:grid(attr.size, attr.numcols, 3)} would use the size attribute of the tag if it was defined otherwise it would use the numcols attribute, if defined. If neither attribute is defined, the constant 3 is used.	<table> ${children:grid(attr.columns, 2)} </table>
${children:stack(param)}	The stack modifier is used in tabbed panels to create table rows and cells for populating a stacked-cell visualization. It creates a horizontal table of labels that can be clicked for each child tag. Clicking one of the labels brings the visualization of the child tag to the top of the stack. The optional parameter specifies which tag attribute of the child tags to use for the label, using the attr.attrName syntax.	<table> ${children:stack(attr.label)} </table>
${attr:attrName}	This variable substitutes the attribute value of a tag at the current location in the pattern. If the attribute does not have a set value, an empty string is inserted.	<input type="text" value="${attr:value}" />
${facet:facetName}	This variable inserts the tag inside a named JSF facet tag at the position of the variable in the pattern.	<table> <tr> <td> ${facet:header} </td> </tr> ${children:grid} <tr> <td> ${facet:footer} </td> </tr> </table>

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.

Binds to multi-valued data (Collection or array)

Select when the tag requires a collection of data instead of a single object.

Default attribute for binding

Select a default attribute for binding from the list when the tag, to which you are binding data, uses an attribute other than value.

Attribute for repeating values

Select a repeating value when the tag is iterative and needs to use a repeating attribute to affect the value of any child tags. For example, in the data table tag, the attribute for repeating values is set to var.

Behavior for drops from Page Data view

There are three options:

Bind

Select when data is bound to the tag. For example, an output text tag should be set to Bind.

Insert child controls

Select when child tags need to be automatically generated for the data inside the target tag. For example, a panel tag should be set to Insert child controls.

Bind and insert child controls

Select when data is bound to the tag and child tags are automatically generated for the data inside the target tag. For example, a data table tag should be set to Bind and insert child controls.

If a child tag is present and either Insert child controls or Bind and insert child controls is selected, the new controls are wrapped in the child tag. For example, when data is dropped on a data table tag with a column child tag, new columns are automatically added to the data table.

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 the child tags template, <${t}:column>${propertyTemplate}</${t}:column> to create a new column.

The child tag can also be used when data is dropped from the Page Data view onto the tag. For more information, refer to Data Binding.

Properties view

This optional section contains user interface elements and layout information for a user-defined Properties View page. Nested child elements can be added beneath the Properties View section to define the contents of one or more tabs.

Tab

A tab contains other UI elements within it and corresponds to the right pane of the Properties View. The tab names are shown on the left side of the view, with the main (first) tab initially displayed. The first tab always has the name of the selected tag so the value of the name attribute for the first tab is ignored.

Column

The Column element visually groups a set of other UI elements into a vertical column. Two or more columns will be defined inside either a Tab or Section element and child controls will be configured within each column. Non-column elements are not supported inside the same container where any columns are used, so sections might be required to separate a multi-column arrangement into its own region.

Editor

Editor elements define what type of UI control are displayed on the Properties View (for example, a radio button), which attribute of the current tag that control will modify, and what string label to display next to the control. You can also add parameters to the editor element.

Editor Parameter

Some editor elements can take optional editor parameters to customize a control's behavior. For example, a Combo Box and other similar selection controls can be configured with a parameter called choices that defines the allowable values. The value of the choices parameter uses the syntax enum{value1, value2, value3} or if separate labels and values are used in the Combo Box: enum{name1:value1, name2:value2}. Most of the other pre-defined editor parameters accept true or false values.

Label

The Label element places a label containing text information in the Properties View.

Section

The Section element is a container that defines a self-contained portion of the UI. Sections can be used to provide control over spacing of the controls they contain. For example, a section can be configured to span multiple columns in a surrounding layout, or to define a new column structure for its own contents.

Separator

The Separator element displays a horizontal rule that divides the Properties View contents.

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 or from the Data drawer of the Palette.

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.

To add a data template, right-click Data Templates and then select Add and the type of template that you want to add to the library definition.

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.