|
[Previous] [Overview] [Next]
Hands on Example: Using Tag Libraries in iQgen
This document will show you how to use your own Tag Libraries (taglibs) with iQgen.
We will use a Tag Library to format date and time data as an example.
iQGen supports JSP 1.1 Tag Libraries. If you want to know how to program Tag Libraries, please consult the
JSP 1.1 Specification or any JSP tutorial.
When to Use Tag Libraries
Tag Libraries enable you to write "simple" templates. This means that Tag Libraries allow you to move complicated logic from your templates into a single tag.
Templates will be much easier to read and to understand if Tag Libraries are used. They can be structured more clearly. As a consequence you should use Tag Libraries
whenever you feel that your templates are getting too complicated, unreadable and unmaintainable.
Deploying Tag Libraries in iQgen
Basically you can deploy every JSP 1.1 Tag Library into iQgen.
There are only a few conditions on Tag Libraries to enable the deployment in iQgen.
First of all the Tag Library has to be packed into a jar file.
The jar file must include a Tag Library Descriptor (TLD).
The TLD is a file that describes the tags contained in the Tag Library.
It is best - but not required - to be placed in the META-INF directory for compatibility with some IDEs e.g. IntelliJ IDEA.
The JSP Engine uses this file to get all the necessary information to process the Tag Library.
Now the Tag Library can be deployed. You have to copy it into a subdirectory taglibs in the home directory of your iQgen installation (e.g.
C:\Programme\iQgen). If the directory does not exist, you have to create it.
Now this Tag Library can be used in all iQgen templates.
If the deployed Tag Library uses any libraries (jar files), they have to be put into a subdirectory of the taglibs directory called lib.
In case you want to use the ANT interface of iQgen a special issue arises. The jar file of the Tag Library then has to be placed in a taglibs directory in the
lib directory of your ANT installation. The reason for this is that iQgen searches the jars of Tag Libraries relatively to the iQgen jar file.
This jar file - in the ANT mode - resides in the lib directory of ANT.
Using Tag Libraries in templates
If you have completed all the steps explained in the previous paragraph, you can use your Tag Libraries in your templates.
Here is some example code which shows you how to access the Tag Libraries:
[...]
<%@taglib uri="your_taglib" prefix="your_prefix" %>
[...]
<your_prefix:your_tag your_attr1="a" your_attr2="b">
In case of a body tag there can be something in here
</your_prefix:your_tag>
[...]
|
The taglib directive (<%@taglib ... %>) makes a Tag Library available within a template.
To do this the uri of the Tag Library and the prefix must be specified as attributes of the directive.
The uri of a Tag Library in the taglibs directory is the filename of the jar file of the Tag Library without '.jar'.
It is used to locate the Tag Library.
Now you can use the Tag Library identifying it using the prefix, you have specified (<your_prefix:your_tag ... >).
The Example: The iQgen Sample Tag Library
The sample will be distributed with iQgen in the next releases.
You will find it in the directory samples/getting_started/taglib_tutorial in your iQgen directory.
As long as it is not included you can download it from here.
The java class com.innoq.generator.samples.taglibs.SampleTag implements the date and time formating feature.
The following TLD is used:
<?xml version="1.0"?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN"
"http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd">
<taglib>
<tlibversion>1.0</tlibversion>
<jspversion>1.1</jspversion>
<shortname>iqgen-taglib-sample</shortname>
<info>Sample which shows you how to use the taglibs</info>
<tag>
<name>date</name>
<tagclass>com.innoq.generator.samples.taglibs.SampleTag</tagclass>
<info>Formats Dates </info>
<attribute>
<name>time</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
</attribute>
<attribute>
<name>date</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
</attribute>
<attribute>
<name>format</name>
<required>false</required>
</attribute>
</tag>
</taglib>
|
The taglib has only got one tag which is called date.
The attributes are time, date and format.
The allowed values for the attribute format are date, time and datetime, which is the default.
If none of these values is given, the default will be used.
The tutorial includes an ANT build file (build.xml). This can be used to compile, assemble and install the Tag Library.
You just have to call the target install resp. install-for-ant in order to make this Tag Library available for the GUI resp. the ANT interface of iQgen.
Here are the important bits of the build file to show you what is done to deploy the Tag Library:
<target name="dist" depends="compile">
<copy file="${basedir}/taglib.tld" todir="${classes.dir}/META-INF"/>
<jar jarfile="${jar.file}" basedir="${classes.dir}"/>
</target>
<target name="install" depends="dist">
<mkdir dir="${generator.dir}/taglibs"/>
<copy file="${jar.file}" todir="${generator.dir}/taglibs"/>
</target>
<target name="install-for-ant" depends="dist">
<mkdir dir="${ant.home}/lib/taglibs"/>
<copy file="${jar.file}" todir="${ant.home}/lib/taglibs"/>
</target>
|
As you can see the taglib.tld is copied in the META-INF directory of the jar file in order to build the jar.
This ensures the correct structure of the jar file.
The install resp. install-for-ant target then copies the jar file into the correct directory.
After having successfully installed the Tag Library there will be a taglibsample.jar in the taglibs directory of your iQgen installation.
Now you can use the taglibsample Tag Library in your templates:
[...]
<%@taglib uri="taglibsample" prefix="datelib" %>
[...]
<datelib:date format="date"/>
<datelib:date time="<%=System.currentTimeMillis() + 3600000%>" format="datetime"/>
[...]
|
This will result in the following output:
09.08.2002
09.08.2002 11:06:43 |
| 
