bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic JSP Tag Extensions

Overview of Programming JSP Tag Extensions

The JSP 1.1 Specification introduced the ability to create and use custom tags in JavaServer Pages (JSP). Custom tags are an excellent way to abstract the complexity of business logic from the presentation of Web pages in a way that is easy for the Web author to use and control. You can use custom JSP tag extensions in JSP pages to generate dynamic content, and you can use a variety of Web development tools to create the presentation.

WebLogic Server fully supports the tag extension mechanism described in the JSP 1.1 Specification.

The following sections provide an overview of JSP tag extensions:

- Overview of Custom Tag Functionality

- Using Custom Tags in a JSP

- Referencing a Tag Library

Overview of Custom Tag Functionality

You write a custom JSP tag by writing a Java class called a tag handler. You write the tag handler class by doing one of the following:

- Implement one of two interfaces, Tag or BodyTag, which define methods that are invoked during the life cycle of the tag.

- Extend an abstract base class that implements the Tag or BodyTag interfaces.

Extending an abstract base class relieves the tag handler class from having to implement all methods in the interfaces and also provides other convenient functionality. The TagSupport and BodyTagSupport classes implement the Tag or BodyTag interfaces and are included in the API.

One or more custom JSP tags can be included in a Tag Library. A tag library is defined by a Tag Library Descriptor (TLD) file. The TLD describes the syntax for each tag and ties it to the Java classes that execute its functionality.

Using Custom Tags in a JSP

Custom tags can perform the following tasks:

- Produce output. The output of the tag is sent to the surrounding scope. The scope can be one of the following:

  - If the tag is included directly in the JSP page, then the surrounding scope is the JSP page output.

  - If the tag is nested within another parent tag, then the output becomes part of the evaluated body of its parent tag.

- Define new objects that can be referenced and used as scripting variables in the JSP page. A tag can introduce fixed-named scripting variables, or can define a dynamically named scripting variable with the id attribute.

- Iterate over body content of the tags until a certain condition is met. Use iteration to create repetitive output, or to repeatedly invoke a server side action.

- Determine whether the rest of the JSP page should be processed as part of the request, or skipped.

Formatting Custom Tags

The format of a custom tag format can be empty, called an empty tag, or can contain a body, called a body tag. Both types of tags can accept a number of attributes that are passed to the Java class that implements the tag. For more details, see Handling Exceptions within a Tag Body.

An empty tag takes the following form:

>     <mytaglib:newtag attr1="aaa" attr2="bbb" ... />

A body tag takes the following form:

>     <mytaglib:newtag attr1="aaa" attr2="bbb" ... >
>       body
>     </mytaglib:newtag>

A tag body can include more JSP syntax, and even other custom JSP tags that also have nested bodies. Tags can be nested within each other to any level. For example:

>     <mytaglib:tagA>
>        <h2>This is the body of tagA</h2>
>        You have seen this text <mytaglib:counter /> times!
>       <p>
>       <mytaglib:repeater repeat=4>
>          <p>Hello World!
>       </mytaglib:repeater>
>     </mytaglib:tagA>

The preceding example uses three custom tags to illustrate the ability to nest tags within a body tag. The tags function like this:

- The body tag <mytaglib:tagA> only sees the HTML output from its evaluated body. That is, the nested JSP tags <mytaglib:counter> and <mytaglib:repeater> are first evaluated and their output becomes part of the evaluated body of the <mytaglib:tagA> tag.

- The body of a body tag is first evaluated as JSP and all tags that it contains are translated, including nested body tags, whose bodies are recursively evaluated. The result of an evaluated body can then be used directly as the output of a body tag, or the body tag can determine its output based on the content of the evaluated body.

- The output generated from the JSP of a body tag is treated as plain HTML. That is, the output is not further interpreted as JSP.

Some Example Scenarios

The following scenarios demonstrate what you can do with custom tags:

- An empty tag can perform server-side work based on its attributes. The action that the tag performs can determine whether the rest of the page is interpreted or some other action is taken, such as a redirect. This function is useful for checking that users are logged in before accessing a page, and redirecting them to a login page if necessary.

- An empty tag can insert content into a page based on its attributes. You can use such a tag to implement a simple page-hits counter or another template-based insertion.

- An empty tag can define a server-side object that is available in the rest of the page, based on its attributes. You can use this tag to create a reference to an EJB, which is queried for data elsewhere in the JSP page.

- A body tag has the option to process its output before the output becomes part of the HTML page sent to the browser, evaluate that output, and then determine the resulting HTML that is sent to the browser. This functionality could be used to produce "quoted HTML," reformatted content, or used as a parameter that you pass to another function, such as an SQL query, where the output of the tag is a formatted result set.

- A body tag can repeatedly process its body until a particular condition is met.

Referencing a Tag Library

JSP tab libraries are defined in a tag library descriptor (tld). To use a custom tag library from a JSP page, reference its tag library descriptor with a <%@ taglib %> directive. For example:

>       <%@ taglib uri="myTLD" prefix="mytaglib" %>

  uri

  The JSP engine attempts to find the Tag Library Descriptor by matching the uri attribute to a uri that is defined in the Web Application deployment descriptor (web.xml) with the <taglib-uri> element. For example, myTLD in the above taglib directive would reference its tag library descriptor (library.tld) in the Web Application deployment descriptor like this:

>     <taglib>

>       <taglib-uri>myTLD</taglib-uri>
>       <taglib-location>library.tld</taglib-location>

>     </taglib>

  prefix

  The prefix attribute assigns a label to the tag library. You use this label to reference its associated tag library when writing your pages using custom JSP tags. For example, if the library (called mytaglib) from the example above defines a new tag called newtag, you would use the tag in your JSP page like this:

>     <mytaglib:newtag>

For more information, see Creating a Tag Library Descriptor.