Using Tag Library Templates

with the JSP Visual Page Editor

(DRAFT)

The Visual Page Editor (VPE) allows you to work with either a visual representation of a JSP
file or with the underlying source code for the JSP file. In order to display a JSP file that contains
tag library tags properly, we need to specify how to render the library tags as HTML tags and
how to use them in the visual representation.
VPE uses an XML template file to specify this for a particular tag library. The templates use tags
and expressions to define how source-tags (the actual JSP library tags) can be rendered as
visual-tags (HTML tags).

Template Files
All template files are located inside this folder:
<ExadelStudioHome>\eclipse\plugins\com.exadel.vpe_x.x.x\templates

One XML file in this folder lists all the templates available to load by VPE in this folder:
vpe-templates-list.xml

This cataloging XML file uses two tags. The root element is <vpe:templates-list>. This
element has one or more child elements of this form:
<vpe:templates file="vpe-templates-taglibname.xml"/>

These are the standard templates listed in the template list file:

vpe-templates-adf.xml template for Oracle ADF tags

vpe-templates-html.xml
vpe-templates-jsf.xml
vpe-templates-jsp.xml
vpe-templates-myfaces.xml
vpe-templates-struts.xml
templates for HTML tags
templates for JSF (RI) tags
templates for JSP tags
templates for MyFaces tags
templates for Struts tags

Creating a New Template

Adding a new template file is pretty straight-forward.

Confidential, Exadel, Inc. ©2005

 Confidential, Exadel, Inc. ©2005

1. Create a new template file inside the templates directory. For example, let’s say vpe-
templates-myTags.xml.
2. Add this entry for your template inside the vpe-templates-list.xml file:
<vpe:templates file="vpe-templates-MyTags.xml"/>
3. The vpe-templates-MyTags.xml file you create should use a <vpe:templates>
element as the root element and begin with a taglib declaration that should match the
taglib declaration used in the JSP file. Here’s an example:
<vpe:templates>
<vpe:template-taglib uri="http://java.sun.com/jsf/html"
prefix="h"/>
……………………………….
</vpe:templates>

Template Structure
Each tag library templates file consists of one or more separate templates for handling particular
source-tags in the tag library. The basic template structure is represented by this code:
<vpe:tag name="a" case-sensitive="no">
<vpe:template children="yes" modify="yes">
<span class="{@class}" style="{@style}color:blue;text-
decoration:underline"/>
<vpe:dnd>
<vpe:drag start-enable="yes"/>
<vpe:drop container="yes">
<vpe:container-child tag-name="#text"/>
</vpe:drop>
</vpe:dnd>
</vpe:template>
</vpe:tag>

Let’s walk through this example.

<vpe:tag name="a" case-sensitive="no">...</vpe:tag>

This means that the template will be applied to both “<a>” and “<A>” source-tags. If the “case-
sensitive” attribute had been set to “yes”, then only “<a>” would be processed.

<vpe:template children="yes" modify="yes">...</vpe:template>

The template includes visual-tags for rendering the matched source-tag and vpe: namespace
tags for further controlling how the matched source-tag is handled in the VPE visual
representation. In the tag itself, the “children” attribute defines if the source-tags nested inside
the visual-tag will be themselves be displayed inside the VPE visual representation. The
“modify” attribute defines whether the visual-tags generated from the matched source-tag can be
edited inside the visual representation.

DRAFT Page 2 of 9
 Confidential, Exadel, Inc. ©2005

<span class="{@class}" style="{@style}color:blue;text-

decoration:underline"/>
This is the actual HTML for the visual-tag that is displayed for “<a>” or “<A>”. Note the
“{@class}” and “{@style}” attribute value templates. These will pick up the values for these
attributes in the source-tag and use them in the visual-tag.

<vpe:dnd>...</vpe:dnd>
This section describes how the visual-tag behaves in the visual view during drag and drop.
<vpe:drag start-enable="yes"/> defines if it’s allowed or not to start dragging the
visual-element. <vpe:drop container="yes">...</vpe:drop> defines if it’s allowed or
not to drop something else inside this visual-tag. And finally, <vpe:container-child tag-
name="#text"/> defines what can be dragged and dropped. In this example it is only plain
text.

Branching to Different Templates

Inside the tag <vpe:tag … >…</vpe:tag> you could include one or more templates inside
vpe:if elements like this:
<vpe:if test="…"><vpe:template …>…</vpe:template></vpe:if>

The result of the “test” expression determines if the template will be applied to the source-tag.
The first template to match is the one that gets applied.

More Template Examples

Using “vpe:copy”
In this simple case, the source-tag itself is passed through as the visual-tag into the visual view.
This applies to most HTML tags. In this case the “<vpe:copy>” tag is used. The attribute “attrs”
determines which attributes of the source-tag will be copied to the corresponding visual-tag.

Source-Tag Template Displayed HTML

<acronym class=”aaa”>
Text in acronym
</acronym>
<abbr style=”color:red;”>
Text in tag ABBR
</abbr>
<vpe:tag name="acronym" case-sensitive="no"> <acronym class=”aaa”>
<vpe:template children="yes" modify="yes"> Text in acronym
<vpe:copy attrs="style,class"/> </acronym>
</vpe:template>
</vpe:tag>
<vpe:tag name="abbr" case-sensitive="no"> <abbr style=”color:red;”>
<vpe:template children="yes" modify="yes"> Text in tag ABBR
<vpe:copy attrs="style,class"/> </abbr>
</vpe:template>
</vpe:tag>

DRAFT Page 3 of 9
 Confidential, Exadel, Inc. ©2005

Using HTML Only

The source-tag can be represented in the visual view with a different HTML visual-tag
representation. This is the most common case.

Source-Tag Template Dipslayed HTML

<a style=”bgcolor:red;”> <vpe:tag name="a" case-sensitive="no"> <span style=”bgcolor:red;color:blue;”>
Text in a <vpe:template children="yes" Text in a
modify="yes">
</a> </span>
<span style="{@style}color:blue;"/>
</vpe:template>
</vpe:tag>

This example shows the usage of “{@style}” in the template “span” tag’s “style” attribute to
include the value of the source-tag’s “style” attribute in the visual tag’s “style” attribute..

Using “vpe:if”
Here is an example of branching to determine which of two or more templates get applied for
rendering a source-tag.

Source-Tag Template Displayed HTML

<input type=”text”/> <vpe:tag name="input" case-sensitive="no"> <input type=”text”/>
<vpe:if test="@type='text'">
<input type=”file”/> <vpe:template children="no" modify="no"> <input/>
<vpe:copy attrs="type"/> <input type="button"
value="Browse"/>
</vpe:template>
</vpe:if>
<vpe:if test="@type='file'">
<vpe:template children="no" modify="no">
<input/>
<input type="button" value="Browse"/>
</vpe:template>
</vpe:if>
</vpe:tag>

Using “vpe:attribute”
This tag is used to add additional attributes to the visual-tag.

Source-Tag Template Displayed HTML

DRAFT Page 4 of 9
 Confidential, Exadel, Inc. ©2005

<img src=”img.gif”> <vpe:tag name="img" case-sensitive="no"> <img src=”img.gif”

border=”1”>
<vpe:template children="no" modify="no">
<vpe:copy attrs="src">
<vpe:attribute name="border" value="1"/>
</vpe:copy>
</vpe:template>
</vpe:tag>

Using “vpe:value”
This tag is used to display a value of a source-tag attribute attribute as text in the visual view.

Source-Tag Template Displayed HTML

<input value=”aaa”> <vpe:tag name="input" case-sensitive="no"> <span>aaa</span>
<vpe:template children="yes" modify="no">
<span>
<vpe:value expr="{@value}"/>
</span>
</vpe:template>
</vpe:tag>

Using “vpe:grid”
This tag specifies that the matched source-tag should be laid out as a table. The “layout” attribute
is used for specifying the table format in the visual view.

Source-Tag Template Displayed HTML

DRAFT Page 5 of 9
 Confidential, Exadel, Inc. ©2005

<h:selectManyCheckbox <vpe:tag name="h:selectManyCheckbox" <table>

layout="pageDirection"> case-sensitive="yes"> <tr>
<f:selectItem <vpe:template children="yes" modify="yes"> <td>
itemValue="black" <vpe:grid layout="{@layout}"/> <span>
itemLabel="Black"/> </vpe:template> <input type="checkbox">
<f:selectItem </vpe:tag> Black
itemLabel="Red" </span>
itemValue="red"/> <vpe:tag name="f:selectItem" </td>
</h:selectManyCheckbox> case-sensitive="yes"> </tr>
<vpe:template children="no" modify="yes"> <tr>
<span title="{tagstring()}"> <td>
<input type="checkbox"/> <span>
<vpe:value <input type="checkbox">
expr="{jsfvalue(@itemLabel)}"/> Red
</span> </span>
</vpe:template> </td>
</vpe:tag> </tr>
</table>
<h:selectManyCheckbox <table>
layout="lineDirection"> <tr>
<f:selectItem <td>
itemValue="black" <span>
itemLabel="Black"/> <input type="checkbox">
<f:selectItem Black
itemLabel="Red" </span>
itemValue="red"/> </td>
</h:selectManyCheckbox> <td>
<span>
<input type="checkbox">
Red
</span>
</td>
</tr>
</table>

DRAFT Page 6 of 9
 Confidential, Exadel, Inc. ©2005

Using of Special Templates

Some source-tags might require special templates to be represented as HTML visual-tags. In
such cases, templates are created especially for them.

Source-Tag Templates Purpose

<link href="file.css"> <vpe:tag name="link" case-sensitive="no"> Visual-tag is not created.
<vpe:template children="no" modify="no"> Allows you to declare
<vpe:link rel="{@rel}"
CSS files.
href="{href(@href)}"/>
</vpe:template>
</vpe:tag>
<f:loadBundle …/> <vpe:tag name="f:loadBundle" case-sensitive="yes"> Visual-tag is not created.
<vpe:template children="no" modify="no"> Allows you to declare
<vpe:load-bundle/>
resource files.
</vpe:template>
</vpe:tag>
<h:panelGrid …/> <vpe:tag name="h:panelGrid" case-sensitive="yes"> Displays JSF tag
<vpe:template children="yes" modify="yes"> <h:panelGrid …/>.
<vpe:panelgrid …/>
</vpe:template>
</vpe:tag>
<h:dataTable …/> <vpe:tag name="h:dataTable" case-sensitive="yes"> Displays JSF tag <h:
<vpe:template children="yes" modify="no"> dataTable …/>.
<vpe:datatable …/>
</vpe:template>
</vpe:tag>
<h:column> <vpe:tag name="h:column" case-sensitive="yes"> Displays JSF tag <h:
<vpe:template children="yes" modify="yes"> column>.
<vpe:column/>
</vpe:template>
</vpe:tag>
<vpe:template children="yes" modify="yes"> Displays any tag for
<vpe:any value="{name()}" title="{tagstring()}"/> which a template was not
</vpe:template>
found.

DRAFT Page 7 of 9
 Confidential, Exadel, Inc. ©2005

Attributes and Functions

When using templates, you often need to access a value from the source-tag. If it’s an attribute
value or a combination of attribute values, use the “{@AttributeName}” feature.

Example
<vpe:tag name="h:selectManyMenu" case-sensitive="yes">
<vpe:template children="yes" modify="yes">
<select style="{@style}" class="{@styleClass}"
title="{tagstring()}"/>
</vpe:template>
</vpe:tag>

Here, the “style” and “class” attributes of the visual-tag, “<select>,” would be assigned the same
values as the same attributes in the source-tag , “<h:selectManyMenu>.”
You can also use these special function in the values for template tag attributes. In the example
above, the “title” attribute of the visual-tag “<select> will be assigned to this string: <vpe:tag
name="h:selectManyMenu" case-sensitive="yes"> The following functions are
available:

String Functions
• name() – element name of the source tree
• src(path) – transform a relative file path to a local file path
• if(BooleanExpression, ret1, ret2) – returns ret1, if BoolenExpression is true and
returns ret2, if BoolenExpression is false
• tagstring() – returns text of the source-tag
• parentname()– returns the name of the parent tag

Boolean Functions
• not(BooleanExpression) – logical negation.
• hasinparents(tagName) – returns true if, in the chain of parents, a tag with name of
tagName is found.
• attrpresent(attrName) – returns true if the tag has an attribute with the name of
“attrName”

DRAFT Page 8 of 9
 Confidential, Exadel, Inc. ©2005

DRAFT Page 9 of 9