# Tag Library Extension Samples

The TaglibExtDevKit sample application includes an extended custom JSP tag, along with a web application in which to test it. Also included in the application is a project that illustrates how to make your custom tag library available to WebLogic Workshop web applications.

The following projects are included in the TaglibExtDevKit application:

- TagHandlers — Handler code for the tag library of which the <tdk:barcode> custom JSP tag is a part.
- TldxHandlers — Code that provides logic for extensions to the tag library.
- TaglibWebProject — A web project to use for trying out the sample extensions.
- TaglibInstall — A project that illustrates how to make a tag library available to web applications.

The first three of these projects are described in more detail under <tdk:barcode>. The last is described under TaglibInstall Sample.

## <tdk:barcode> Sample

The <tdk:barcode> tag sample provided with this release illustrates the basics of extending a custom JSP tag library. As described in Developing Tag Library Extensions, you extend a tag library in order to integrate the tag with the WebLogic Workshop IDE.

Note that if you haven't already, you will need to build the sample in order to see it working in the IDE. For more information, see Building and Running the Sample.

The code for this sample (and other extended JSP tags) can be divided into two categories:

- Standard JSP tag code. This includes the tag handler in the TaglibExtDevKit sample application, at TagHandlers/TDK/Barcode.java. It also includes the tag library's TLD file, located in the TaglibWebProject application, at WEB-INF/tdk-tags.tld. Keep in mind that this handler conforms to the standard for JSP tags (for example, it extends the BodyTagSupport class).
- Tag library extension code. This includes handler classes that provide user interface integration with WebLogic Workshop. It also includes the extension's TLDX file, located in the TaglibWebProject application, at WEB-INF/tdk-tags.tldx. This file describes the extension's characteristics, pointing to the extension handler classes where needed. For more information on TLDX files, see TLDX File Contents.

### Features Illustrated by this Sample

The <tdk:barcode> sample illustrates a few basic areas where tag library extensions provide tag integration with WebLogic Workshop. In Design View, the tag displays a barcode representing whatever value you type into the tag's value property attribute.

- Using a renderer class to customize tag display in Design View. The Renderer class displays a barcode symbol (created by the BarcodeEncodings class) based on the value attribute.
- Using a palette generator class to customize how the tag is listed in the Palette. The PaletteGenerator class defines where and how the custom tag will appear in the WebLogic Workshop Palette.
- Using several TLDX elements to define other characteristics. These include how the <tdk:barcode> tag should be formatted in source code.

### Support for Help

To illustrate help integration, the <tdk:barcode> sample provides a few placeholder topics that are displayed when the user presses F1. This is typical for custom tags and controls used in WebLogic Workshop.

Note: As installed, these topics don't open in the frameset used by other topics. To enable this, you will need to include several templates that all workshop help files include. For the GA release of WebLogic Platform 8.1, we do not provide these templates, but you are encouraged to look at the source of any of our help files if you would like to reproduce this functionality.

### Building and Running the Sample

This section describes how to build components of the TaglibExtDevKit sample application so that you can run the TaglibWebProject sample and see the result. You needn't perform these steps in order to merely browse the sample code.

1. In WebLogic Workshop, open the TaglibExtDevKit application.

   In the Extension Development Kit, the WORK file is located at ExtensionDevKit/TaglibExtDevKit/TaglibExtDevKit.work.

2. Build the TagHandlers Java project: In the Application pane, right-click the TagHandlers folder, then select Build TagHandlers.
3. Build the TldxHandlers Java project: In the Application pane, right-click the TldxHandlers folder, then select Build TldxHandlers.

   Building the project will compile and package the sources. It will also copy resulting JAR to the workshop/extensions folder where the tab library extensions can be found the IDE, and it will copy the documentation in the project to the correct location in the help hierarchy (workshop/help/doc/en/tldx).

4. Restart the IDE to pick up changes.
5. Finish integrating the tag library documentation by rebuilding the search index. From the Help menu, select Rebuild Search Index. This may take a few minutes.

   Note that after you rebuild the index, you will only need to rebuild it again if you have either added new help files or modified the toc.xml file.

6. Update the test client web application to include the newly built tag library extensions. In the Application pane, right-click the TaglibWebProject folder, then select Install -> Web Project Libraries. In the Web Project Libraries dialog, select the All Web Project Files check box, then click Install.

   The Web Project libraries need to be in sync with the version of WebLogic Workshop that is currently running.

7. Try out the extensions that support Design View. Open TaglibExtDevKit/TaglibWebProject/demo.jsp. With demo.jsp in Design View, click the tag in the design. In the Property Editor, edit the value attribute. Notice that as you change the value, the barcode updates to represent the new value. Also, note that there is a .:TDK tags:. category in the Palette, along with a .:barcode:. tag so that you can add new instances of the tag to the page design.
8. Run demo.jsp to test the tag handler. Right-click the JSP design, then select Run JSP. If you are prompted to start WebLogic Server, click OK.

   demo.jsp should open in a Test Browser. If the test is successful, the browser will display the following text:

   > SUCCESS: value to encode=value_of_value_attribute

## TaglibInstall Sample

This sample demonstrates how you can write an extension that enables your tag libraries for use in web projects.

To use this sample, use the following steps:

1. Right-click on the TaglibInstall project and select Build TaglibInstall.

   The build target copies an extension jar into workshop's extension folder and a template archive into workshop's template folder.

2. Restart the IDE and create a new web project in your application.
3. Right-click on the new webapp project in the application pane, then click Install -> TDK Taglibs.

   This copies the files from the template archive into the webapp directory structure.

   Additionally, a new entry for the taglib is created in the web project's web.xml. Together, these steps make the TDK taglibs available to the user for this web project.

The logic for this process is captured in TaglibInstall/TDK/TemplateProcessor.java. The processor class must implement com.bea.ide.workspace.project.IProjectTemplateProcessor and be referenced in the template archive's template.xml file (for an example, see TaglibInstall/template/template.xml).

Related Topics

None.