JSP-Page Writing Guidelines

To be able to use WebObjects components in your JSP pages, you have to include the WOTaglib_1_0.tld custom tag library. It's located in /System/Library/Frameworks/JavaWOJSPServlet.framework/Resources. This custom tag library uses the tag library descriptor format defined in a DTD (Document Type Definition) from Sun. This DTD is available at http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd.

The tags you use in your JSP pages have the form <wo:tagName>. tagName indicates the type of element you want to use. For example, to use a component element within a JSP page, you add code like the following to the .jsp file:

<wo:component ...>
    ...
</wo:component>

Version 1.0 of the custom tag library defines five tags as described in Table 3-1.

Table 3-1 Custom tags defined in WOTaglib_1_0.tld

Tag	Children	Description
`<wo:component>`	`binding` `extraHeader`	Top-level element. Specifies the component that is used in the JSP page.
`<wo:directAction>`	`formValue` `extraHeader`	Top-level element. Specifies the direct action that is used in the JSP page.
`<wo:extraHeader>`	None	Specifies the extra HTTP headers to be passed to the component or direct action.
`<wo:binding>`	None	Specifies the key-value pair to be passed to the containing `<wo:component>` for binding.
`<wo:formValue>`	None	Specifies the form value to be passed to the containing `<wo:directAction>`.

For detailed information on the WebObjects custom tag library, see "Custom-Tag Reference".

To use the <wo:component> or <wo:directAction> tags on a JSP page, you must add the following directive to the page:

<%@ taglib uri="/WOtaglib_1_0.tld" prefix="wo" %>

When you need to access WebObjects classes or objects from your JSP page, you need to copy all the framework and application JAR files necessary into the WAR file. You accomplish this by calling the initStatics method of the WOServletAdaptor class:

<% WOServletAdaptor.initStatics(application); %>

Note that you need to invoke the initStatics method only once during the lifetime of an application. Furthermore, anytime a <wo:component> or <wo:directAction> tag is used in a JSP page, the method is invoked automatically.

You also need to import the appropriate packages before using the classes with the import attribute of the page directive in your JSP page:

<%@ page import = "com.webobjects.jspservlet.*" %>

These directives need to be performed only once per page. However, additional invocations have no ill effect. Referencing classes directly is useful when using components that require binding values—for example, a WORepetition whose list attribute is bound to an array of enterprise-object instances.

This is an example of a directAction definition:

<wo:directAction actionName="random" className="DirectAction">
    <wo:formValue key = "formKey" value = '<%= "formValue" %>'/>
    <wo:extraHeader key = "headerKey" value = '<%= "headerValue" %>'/>
</wo:directAction>

This is an example of a component definition:

<wo:component className="MyImageComponent">
    <wo:binding key="filename" value='<%= "start.gif" %>' />
</wo:component>

To embed dynamic elements in a JSP page, such WOConditional and WORepetition, you have to wrap them in a WebObjects component, which you then use in your JSP page.