Configuring the JSP Library Definition

A JSP Library Definition contains project resources that are needed for a component library and the metadata necessary for the interpretation of JSP tags. It helps you to customize the integration of a custom JSP tag library into this product.

Procedure

  1. Double-click your JSP Library Definition to open the library definition file in the editor. Your library definition file has a CLD extension.
  2. Make any necessary changes to your library definition. The library definition file includes the following sections:
  3. After you configure your library definition, save the file. The definition is updated.
  4. 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.

JSP Library Definition

The JSP Library Definition editor is used to configure the details about how to incorporate a new JSP library into the project.

About this task

Library name
Name of the library.
Description
A description of the library.
Taglib URI
The taglib URI of the component library.
Prefix
The prefix that is given to the tags.
Version
The version number indicates the level of the configuration in the library definition. It signals when newer resources might 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. After 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 might need a version update. If any changes are made in the Application Configuration section of a deployed library definition, increase the version number. The increased version number indicates to the workbench that newer resources or configuration changes are available. Any web projects that use the tag library are marked with an error. The Quick Fix associated with that error can update the web projects with the current configuration.
Remember: If a tag library is not 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

The following details how to set up the web project to use the new component library. The configuration declares how to copy files into the web project and any configuration changes that must be made to make components function properly.

About this task

Resources
The resources area is used to define files to copy into a web project when a library is first used. The source path is the relative path to a file within the JSP 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. This target path results in a copy of the CSS file that is placed into the /theme folder of the web project.
web.xml Updates
There are several types of modifications that are made to the deployment descriptor of a web project where the 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 select the item from the dialog box.
Servlet
Defines parameters for a new servlet to be added to web.xml.
Context parameter
Records the details for adding a context parameter in the web deployment descriptor. When the library is first used in a web project, the web.xml file is modified to include this information.
Filter
Defines a new filter, which is added into the web.xml file. Initialization parameters for this filter are added by clicking Add in the editor.
Initialization parameter
Collects data for an initialization parameter for a web.xml filter definition.
URL Mappings
Collects any URL-based mappings for the filter.
Servlet Mappings
Collects filter mappings that are based on a servlet name, which is defined in web.xml.

Tag Library

The Tag library lists all of the custom tags that make up the library and enable the configuration of tool behavior. For example, you can specify the appearance of tags in the Palette, behaviors when tags drop onto the editor, the visual appearance of components in web page source, and various details about tag attributes and data binding.

About this task

You can configure details about the tags in the component library. When the library definition is generated, it contains all of the tags in the component library. You can change the order of tags with the Up and Down buttons. The specified tag order is shown in the appearance of the library in the Palette.

Some visual information about the library palette category can be configured. Configure any style sheet links or JavaScript references that apply to all tags in a library here. When a tag is added from the palette, the corresponding <link> and <script> tags are added to the web page.

Tag
Configures the appearance of the component tag in the palette, including icon and label information. The tag can also be hidden by default or removed from the palette choices.
Drop properties
The behavior of inserting new tags from the palette is modified by parameters on this page. If the component is a container-like control and other components are allowed as children, select Allows children. Style sheet links, JavaScript references can be specified on a tag-by-tag basis on this page. Style sheet 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 components, the display of the tag in the visual page editor renders correctly. In some cases, 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 problem 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 in 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. 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. The description and examples provide information about 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. Child tags are inserted in the order they appear in the original page. The page editor computes the visualizations for the child tags since they can also use patterns. Since all child tags are inserted in the same location, a pattern can use only one ${children} variable.
<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 parameter 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}" />
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 affects how they are shown and edited in the Properties view. Certain types indicate a set of available choices or a specific helper dialog box to assist in setting an attribute value.
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 Properties View. The tab names are shown in theview, 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 are defined inside either a Tab or Section element and child controls are configured within each column. Non-column elements are not supported inside the same container where columns are used. You might be required to separate a multi-column arrangement into its own region within sections.
Editor
Editor elements define:
  • Which type of user interface controls are displayed on the Properties View, such as a radio button.
  • Which attribute of the current tag the user interface control modifies.
  • Which string label to show next to the user interface control.
You can also add parameters to the editor element.
Editor Parameter
Some editor elements can take optional editor parameters to customize the behavior of the control. For example, you can configure a combination box and other similar selection controls using the choices parameter 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 combination box: enum{name1:value1, name2:value2}. Most of the other predefined 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 uses a horizontal rule to divide the Properties View contents.
Icon that indicates the type of topic Task topic
Timestamp icon Last updated: July 17, 2017 21:58

File name: tconfiglibdefjsp.html