[Previous] [Overview] [Next]

JSP Syntax

iQgen internally uses a Java Server Pages (JSP) 1.1 engine to execute your templates. If you are familiar with JSP syntax, developing templates with iQgen should be a piece of cake. However, as not everybody can be fluent in JSP, we will give a short introduction.

A JSP's content is a mixture of literals, directives, declarations, scriptlets, and actions. Sun's JSP syntax card gives an excellent overview of which syntactic elements are legal in a JSP. The following paragraphs cover the most important of these elements. If you are familiar with JSP, you may skip this section and continue with how JSP are used in iQgen.

Declarations

To understand the concept of JSP a little bit better it often helps to know, that each JSP is compiled into a Java class. Like any other class this class has methods and fields. Not surprisingly you can also declare methods and fields in a JSP. This is done like this:

I.e. if you wanted to declare a method getDate() which returns the current date, you could write:

You might have noticed that instead of simply writing Date, we used the fully qualified classname java.util.Date. Of course this is very tedious, if you have to use classnames like com.great.company.with.a.very.long.name.util.MasterUtility. No one likes to write classnames like this. Therefore each JSP can import packages. The mechanism is exactly the same as in Java - just the syntax is different:

Example:

Ideally you place such a page directive at the top of your page. Additionally to the packages you want to import, the page directive lets you specify a class you want to extend. As mentioned before, a JSP will be compiled into a special Java class. This class may inherit some of its behavior from a superclass. To specify this superclass, you may place a page directive with an extends attribute in your page:

Example:

You probably have guessed that you cannot simply subclass any class. Contrary to ordinary JSP engines, iQgen restricts you to extend com.innoq.generator.jsp.JspBase or any of its subclasses. This ensures that certain functionalities expected from iQgen are always available in your templates. If you do not specify a class you want to extend, iQgen will automatically use com.innoq.generator.jsp.JspBase as default class.

Of course declaring methods and inheriting functionality does not get us very far. At least it does not generate any output. Therefore we want to explore means of generating...

Literals

Everything you write in a JSP that isn't marked with special tags (usually starting with <% and ending with %>) will be copied to the output of your template literally. And everything means everything - in particular this rule applies also to whitespace such as tabs, spaces, and newlines.

Expressions

Expressions provide you with a way of inserting the value of objects or primitives (int, float, boolean, ...) into the output. In the case of primitives the value is printed, in the case of an object either null is printed or the result of the toString() method. The syntax is as follows:

Example:

This prints the current date. Of course you can also use other Java expression such as the conditional ? : operator, a method invocation, or any combination of valid expressions.

Scriptlets

With the means we introduced so far, we cannot use control structures like loops or embed a great deal of logic in our templates - or at least not in a reasonable way. Scriptlets offer you a way to easily embed any valid Java code, you could otherwise write in a method, in your template. Note that you cannot declare methods here.

And this is how you can write a loop with a scriptlet:

In the first scriptlet the block that shall be executed 100 times is opened with a curly brace; in the second scriptlet it is closed again. In between we placed a literal (Number:) and an expression (<%=i>). They will both be evaluated, i.e. printed, 100 times.

Please note that this might look very practical and simple, but is actually a maintainance nightmare. Often taglibs (we will talk about them later) do a much better job at encapsulating control structures like conditional execution (if) or repeated execution (for, while).

Including Files statically

JSP are capable of including other files, which are statically compiled into your template and executed as if they have always been part of your template. Syntax:

This is often very useful, if you have a lengthy import section in all your JSP or a copyright notice that always stays the same. Simply include it, where you need it. Example:

Please note that you can include files containing literals as well as scriptlets or any other element of a valid JSP.

Implicit Objects

Of course JSP aren't executed in a vacuum. To access your environment you can use a number of implicitly declared variables. Some of them are listed in the following table:

Name	Type	Comment
request	javax.servlet.ServletRequest	The request from the generator.
response	javax.servlet.ServletResponse	The response to the generator. Not typically used by iQgen authors.
pageContext	javax.servlet.jsp.PageContext	You can store objects in this context.
out	javax.servlet.jsp.JspWriter	The Writer the output is written with.

Taglibs

As mentioned above, taglibs provide a much cleaner way of encapsulating certain tasks or logic. In order to use a taglib, you first have to register it with the page you want to use it in. This can be done with the taglib directive. Syntax:

iQgen comes with a default taglib with the URI iqgen. To use a custom taglib you need to place it in the taglibs directory. The uri refers to the name of the taglib JAR file without the .jar suffix. Once you have registered the taglib, you can use it with the prefix you chose in the taglib directive:

iQgen comes with a prebuilt taglib, which we will mentioned again later.

Further Resources

Since JSP aren't brandnew anymore there are plenty of books and online tutorials around.

Please continue to read the next section on how to use JSP in iQgen.