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.
Before you begin
Procedure
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:
- Select web.xml.
- 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.
- 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.