Chapter 6   Creating Presentation Layout


This chapter describes how to create the pages that make up your application user interface.

The following topics are described in this chapter:

• About Presentation Layout

• Adding HTML Pages

• Displaying Pages Using Different Views

• Editing Text with the Format Toolbar

• Adding Components with the Palette

• Adding Objects by Dragging and Dropping

• Creating Hyperlinks

• Creating Forms

• Adding Images

• Inserting Calls to Servlets or Enterprise JavaBeans

• Validating Data Entered on a Form

• Binding JavaServer Page Components to Dynamic Data

• Using RDBM Tag Library

About Presentation Layout

---

Application developers control the presentation layout of an application with HTML pages and JavaServer Pages (JSPs).

HTML Pages are files containing information to be displayed on a browser. Pages can include graphics, tables of data, and input forms, depending on the designed look and feel of your application.

Some pages are static and unchanging, but some are produced dynamically using JavaServer Pages, and servlets.

A JavaServer Page (JSP) is an HTML file, with Sun-specified JSP 1.1 compliant markup that is executed on the web or application server instead of on the client browser. It dynamically creates pure HTML, which is then sent to the client. The JSP has some new keywords—extensions found only in JSPs—which allow the author to embed scripts and expressions in JSP 1.1 scripting language; incorporate other JSPs from the server (conditionally or unconditionally); call Java Servlets; call Enterprise Java Beans (EJBs) to perform tasks on the server; generate output to be incorporated into the dynamic HTML stream, and use JSP 1.1 tag extensions.

JSPs are compiled into Java by the application or web server the first time they are used. After that, they run without recompilation. The reason for using JSPs is to isolate all the dynamic aspects of a web page construction on the server and to leave the browser to just perform display operations. The Application Builder is in control of available features; all the client has to be able to do is display HTML and run JavaScripts.

JSPs act as output templates, separating the presentation of dynamic content from the generation of that content. They use HTML to describe page layout elements, for placement of items such as text and graphics on the page, and page content elements, which determine dynamic content by accessing system variables and business objects, such as Enterprise JavaBeans.

To use JSPs for your application's presentation layout, you can import existing JSPs and then use the HTML editor text view to edit the embedded Java code.

For more information about Java Server Pages, see the Programmer's Guide.

Adding JSP Files

To add a JSP file, perform the following actions:

1. Choose the Add File(s) menu item from the Project menu.

2. Select All Files for the type file.

3. Locate the file in the iASRoot directory.

4. Click Add to add the file to your project.

   
   
   

Testing and Deploying Pages and JSP Files

Once you have created the required HTML pages and JavaServer Pages for your presentation layout, you can use iPlanet Application Builder to test and deploy them.

Testing HTML Pages and JavaServer Pages

iPlanet Application Builder enables you to test your application's presentation layout by viewing them in a browser.

For more information about how to test HTML pages and JSPs, see "Testing and Deploying Pages and JSP Files."

Deploying HTML Pages and JavaServer Pages

Static pages can be deployed to the web server's HTTP document directory, if there is a web server. You deploy and store JSPs with the other business logic components on the application server.

For more information about deployment, see "Deploying Applications."

Components and the Palette

iPlanet Application Builder provides a number of prebuilt components that you can add to your HTML pages and JSPs to support your application. A component's properties control its behavior and appearance. You can customize a component by editing its properties.

Components are organized by type into tabs on a palette. See "Adding Components with the Palette".

Editing Pages and JSPs

You edit static pages and dynamic JSPs using the same methods. The principal difference between them is that static pages are served directly to the browser when called, while JSPs must first be merged with data. For this reason, some components have different properties on JSPs rather than on static pages.

In general, you create pages by running iPlanet Application Builder wizards, and then customize the results by editing existing components and adding new ones. You create JSPs by manually adding the necessary JSP tags to your project files.

Several wizards exist that can help you create application functionality by building pages. For more information, see "Using Wizards to Generate Project Files."

Adding HTML Pages

---

You can add HTML files to a project in three ways:

• Create a new individual page, as described in "Creating and Managing Projects."

• Add existing pages to the project, as described in "Creating and Managing Projects."

• Use one of the available wizards to create functionality, resulting in both pages and necessary source code.

These wizards are described in detail in "Using Wizards to Generate Project Files."

Displaying Pages Using Different Views

---

You can view pages from three perspectives:

• Layout view shows approximately how the finished page looks at runtime, within certain limits.

• Outline view displays the page according to its HTML tag structure.

• Source view displays the HTML source code that defines your page.

Select a view by clicking one of the tabs at the bottom of the HTML editor window. You can edit items on a page or JavaServer Page (JSP) in any of the three available views.

Using Layout View

Layout view displays the page or JSP in WYSIWYG format, although it may not always appear as the user sees it. Nonvisual components are shown along with the visual components and text. Also, the design-time appearance of dynamic JSP components is often different from their runtime appearance, which can be modified or completely generated by a servlet. For example, a JSP component might show up on screen as userName, while at runtime this is replaced with an actual name.

The following image shows the HTML editor window in Layout view:

You can add a component to the page by dragging it from the palette into the HTML editor window in Layout view. You can also enter and edit text directly in Layout view at the cursor location. You can insert carriage returns from the keyboard to create new lines, add calls to servlets using the Insert menu, format text using the format toolbar, and drag existing components around the page to change their positions.

Using Outline View

Outline view displays a hierarchical organization of the HTML tags that make up the page. Use this view to work more directly with the page structure.

Selected objects in the outline view also appear in the properties window, where you can examine and change their properties.

The following image shows the HTML editor window in Outline view:

Using Source View

Source view displays the HTML source code for the page in a text editor window. You can edit the page source directly using this view.

The following image shows the HTML editor window in Source view:

Some JavaScript code appears on HTML pages between comment tags that signal the begin and end of generated code. Do not edit these tags or the code between them, as they are generated and updated by the Editor Beans controlling that component. Editor Beans are Java objects that generate and maintain components.

For example, the code shown in bold below should not be edited:

<SCRIPT PURPOSE="EVENT_HANDLER"
SCRIPTID="document.Form1.select12.onchange"
LANGUAGE="JAVASCRIPT">
<!--
function document_Form1_select12_onchange() {
alert("user defined event" );
//!! begin generated code !!
if (this.selectedIndex != 0) location = this.options[this.selectedIndex].value
//!! end generated code !!
}
//-->
</SCRIPT>

Additionally, you can use the Source view to embed Java code within JavaServer Pages.

Editing Text with the Format Toolbar

---

Use the format toolbar, shown below, to edit HTML text in Layout view:

These tools allow you to set the paragraph type, change typeface details, set indentation, and create lists. These tools can also be found on the Format menu. The tools are described in the following table:

Table 6-1 Formatting Tools

Format Tools	Description
paragraph tag	Set the paragraph type for this paragraph. Options include Normal (<p>), List Item (<li>), and Headings (<h1> through <h6>).
font type and size	Set the typeface (fixed- or variable-width) and text size.
text color	Set the color for the text foreground. An invisible background is assumed.
text style	Set text style to bold, italic, or underlined. Click to remove all stylistic formatting.
list style	Set list style to bulleted or numbered. Clicking a list style button on an existing list of the same style converts the list to a set of paragraphs.
indentation	Increase or decrease the level of indentation for a paragraph.
paragraph alignment	Align the paragraph to the left, right, or center of the text column.
link	Convert selected text to a hypertext link.
remove all styles	Remove all style attributes and return to default style.

Adding Components with the Palette

---

Components are reusable objects that appear on an HTML page or JavaServer Page (JSP). Examples include data from a database, images, hyperlinks, form elements such as text entry boxes and Submit buttons. The behavior and appearance of components are defined by their respective properties, which can be edited using the properties window. For more information, see "Creating and Managing Projects."

Components can be Java objects called Editor Beans that generate the required HTML and JavaScript code, depending on the environment into which they are inserted; for example, a text field that generates <rdbm:field> tags to data-bind the VALUE attribute at runtime. Note that the code generated by Editor Beans should not be edited; see "Using Source View".

iPlanet Application Builder contains many pre-built components organized on a palette. Many of these components are standard HTML and JSP elements that have been enhanced to include information used by the iPlanet Application Server, while others are standard HTML tags.

For more information on individual components, see "Component Reference."

About the Palette

Components reside on the palette. Choose Palette from the View menu to launch the palette.

To display a Tooltip that describes the component, move the cursor over the component's icon on the palette. Click the "List view" button in the upper left corner of the window to display the palette items as a list.

The following images show the palette tabs:

Components are grouped into palette tabs, which are shown as short window extensions on the palette. To access components on a given tab, click the tab's name. The following table describes the default palette tabs:

Table 6-2 Default Palette Tabs 

Palette Tab	Description
HTML	Components that consist of standard HTML tags, such as Table, Image, and Data-Bound Link. See "HTML tab."
Form	HTML form elements, such as TextField, CheckBox, and PushButton. See
JSP	Components that provide Directives, Expressions, Scriptlets, Declarations, Beans, Properties, Parameters, and plugins.
RDBM	Components for creating RDBM Queries, Loops, Fields, Parameters, Close, Execute, and GoRecord.

Working with Components

To use a component, you add it to your HTML page or JSP by dragging its icon from the palette and dropping it onto the page in Layout view. Note that some data-bound components are only useful in JSPs, and thus can not be dropped onto a static page. For more information on using data-bound components, see "Binding JavaServer Page Components to Dynamic Data".

You can edit a component's properties to change its behavior or appearance. For more information, see "Viewing and Editing Project File Properties."

You can also drag an edited component back onto the palette for later re-use. For more information, see "Customizing the Palette" in "Setting iPlanet Application Builder Options."

Editing Tags and Components with the Properties Window

Each component and HTML tag behaves according to characteristics defined by the component's properties. You can edit many of these properties with the properties window.

To view or edit the properties of a component or HTML tag, right-click the item in Layout or Outline view and select Properties. The Properties window appears.

To edit a property, click the property definition on the right. For more information, see "Viewing and Editing Project File Properties" in "Creating and Managing Projects."

Some properties show a customization button

to the right of the property definition box when you edit the definition. This button launches a custom property editor for that property, which helps you specify the property value. For more information, see "Using Custom Property Editors" in "Creating and Managing Projects."

Converting Component Types

You can convert some components to other, similar components if you want to change their appearance or behavior.

To convert a component, click and hold the right mouse button on the component you wish to convert. The Change Type drop-down option, shown below, lists the component types to which you can convert:

Select the type of component you want. The component converts to the new type.

Adding Objects by Dragging and Dropping

---

You can move or copy objects from one place to another by dragging them with your mouse. Many objects can be dragged and dropped within the page or from the palette or the Project window. Objects dragged into a page or JSP from outside are copied, while objects dragged within a page are moved.

You can insert a component onto a page by dragging it from the palette and dropping it onto your page (in Layout view) where you want it to appear. The properties window shows the properties for the component.

The following table shows the types of files you can drag from the Project window and drop onto a page or JSP:

Table 6-3 Project Window Drag and Drop File Types 

Type of File	Result when dropped onto an HTML page or JavaServer Page
Static HTML page	Creates a hypertext link which points to the dropped page.
GIF or JPG image	Inserts the image onto the page in an Image component.
Servlet	Prompts you to choose whether to create a form or a hypertext link to call this servlet. For more information, see .
JavaServer Page	Prompts you to choose whether to call the JSP as a form or hyperlink, or, if you drop a JSP onto another JSP, to include the dragged JSP's contents using a JSP include directive. Choose to call the dragged JSP using a form or hyperlink if you wish to create a hypertext link to the JSP. Choose to use a JSP include directive if you want the contents of the dragged JSP to be included at transition time.

Creating Hyperlinks

---

A hyperlink is an active section on a page, usually text or an image, which leads to a new page when it is clicked.

You can create text hyperlinks in the following ways:

• Select text and click on the link icon.

• Drag the Data-Bound Link component onto your JSP from the palette and edit its properties.

• Drag an HTML page from the Project window onto your page. A hypertext link is created, with the directory path to the page as the initial text.

• Drag a JSP or servlet from the Project window onto your page. You are prompted for information about the link.

You can create a data-bound text link in the following way:

• Drag the DropDownLink component onto your page from the palette, and edit its properties. This component creates a drop-down box where each item is a hyperlink; when a reader selects an item, the corresponding URL is loaded into the current window or frame.

You can create an image hyperlink in the following way:

• Create an image, select it, then click the Link icon in the toolbar.

You can create a data-bound image hyperlink in the following way:

• First, add the required image to your project (see "Adding Images"). Next, drag the Data-Bound Image Link component onto your page from the palette. Edit its properties, specifying your image as the Image Source.

Creating Forms

---

You can create forms in the following ways:

Drag any form component from the Form palette tab onto your page. A form is automatically generated around the component. To create a Submit button on the form, drag the PushButton component into the form.

• Drag a JSP or servlet from the Project window onto your page. You are prompted for information about the link. To create a form, choose to link to the servlet with a form.

Adding Images

---

To add an image to a page or JSP, first copy the image to your web server's root document directory, or to your root project directory. Add the image to your project with the following steps:

1. Choose Add Files from the Project menu or New File from the File menu.

2. Click the Existing tab on the New File(s) dialog box.

3. Locate the image in the file system subdirectory and click Add.

4. Drag the Image or Data-Bound Image Link component from the palette to the location on your page (in Layout view) where you want the image. The component's properties appear in the properties window.

   Alternatively, drag the icon representing the image from the Images folder in the Properties window onto your page. This creates an Image component with this image as the source.

5. Click the Image Source property definition in the properties window. You are prompted to choose an absolute or relative URL pointing to the source for this image. For more information, see "Editing Image URLs" in "Creating and Managing Projects."

Inserting Calls to Servlets or Enterprise JavaBeans

---

Since JavaServer Pages are compiled into servlets when they are first accessed, you can perform presentation logic tasks with JSPs as well. For more information, see the Programmer's Guide.

This section includes the following topics:

• Inserting Calls to Servlets

• Inserting Calls to Enterprise JavaBeans

Inserting Calls to Servlets

To insert a call to an existing servlet you insert a link that calls that servlet. You can insert a call to an existing servlet in four ways:

• Drag the icon representing the servlet file from the Project window and drop it on your HTML page or JavaServer Page (JSP).

• Select Call Existing Servlet from the Insert menu or the right-mouse menu. Choose an existing servlet or browse for one not listed.

• In any hypertext link component (DropDownLink, Data-Bound Image Link, Data-Bound Link), you can specify a servlet as the target of the link. Note that you must provide input parameters if the servlet requires them.

• In any form, you can specify a servlet as the action taken when the Submit button is pressed.

In the first two cases, you are next prompted to choose whether to create a form or a hypertext link to call this servlet. If you choose to create a hypertext link, you are prompted to provide default values for the servlet parameters, and a hypertext link is inserted onto the page.

If you choose to create a form, a basic form is inserted onto the page with appropriate input fields for each of the servlet parameters. The form's Action property automatically refers to the specified servlet. If the file you are calling the servlet from is a JSP, the form components can be populated with data dynamically; see "Binding JavaServer Page Components to Dynamic Data".

If you already have an existing form, you can choose a servlet as the action taken when the Submit button is pressed by setting the form's Action property. Select the Action property, click the custom property editor icon, and then select the servlet you want to call. For more information on this custom property editor, see "Creating and Managing Projects."

You can create a new servlet and insert a call to it all in one step by selecting Call New Servlet from the Insert menu. You are prompted with a series of dialog boxes to create a new servlet and forge the link to it from your page or JSP.

For more information on servlets, see "Creating and Editing Servlets" in "Creating Presentation Logic."

Inserting Calls to Enterprise JavaBeans

iPlanet Application Builder does not provide built-in support to call Enterprise JavaBeans (EJBs) from an HTML page or JSP. However, you can use the EJB API Helper to insert a call in a servlet or within the Java code in a JSP to call an EJB.

Validating Data Entered on a Form

---

Validation is a runtime check for the validity of user-entered data, such as a social security number or date. The TextField and Text Area components, both found on the Form palette tab, can be validated by a script when text is entered into them. If the user enters inappropriate data, a dialog box appears with a message explaining what data is expected in this field.

Validation is handled by a JavaScript file called validate.js. You should never need to edit this file directly.

To set up a TextField or Text Area component for validation, perform the following steps:

1. Select the component's Validation property.

2. Select one of the following validation types from the drop-down list:

   
   

   Table 6-4 Validation Types
   
   

   Validation Type	Description	Example of Valid Data
   (none)	No validation. This is the default.	anything
   Integer	Positive or negative integer.	-4, 0, 4, 44, 444
   PositiveInteger	Integer greater than or equal to zero.	0, 4, 44, 444
   Number	Any real number.	-12.5, 0, 12.5, 1000000
   Alphabetic	Alphabetic characters A-Z a-z, and spaces.	A man, a plan, a canal
   CreditCard	Standard credit card number.	1234 5678 9012 3456
   USPhone	10-digit US telephone number.	(123) 456-7890
   InternationalPhone	International telephone number.	011 23 4 567 890
   Email	Email address, like user@domain.	jefro@haven.com
   SSN	A 9-digit social-security number.	123-45-6789
   USDate	A date as mm/dd/yy or mm/dd/yyyy.	12/31/99
   IntlDate	A date as dd/mm/yy or dd/mm/yyyy.	31/12/99
   Year	A 2- or 4-digit integer.	99, 1999
   Month	An integer between 1 and 12.	1, 2, 3
   Day	An integer between 1 and 31.	1, 15, 31
   StateCode	2-character US state code.	CA, NY, AK
   ZIPCode	US ZIP or ZIP+4 code.	94043, 94043-1234
   (Custom)	Custom validation.

3. If you choose (Custom), you must provide the JavaScript code for your custom validation in the Validation Expression property.

   The expression is evaluated in the context of the field you want to check, thus, you can use unqualified properties in your JavaScript code. Often, you need to use the value property, which contains the field's value. For example, the following expression specifies validation of a field so that its values are between 10 and 20:

   (value >= 10) && (value <= 20)

   If you want to only accept entries that contain the string `scape,' as in iPlanet, you could use the following expression:

   value.indexOf("scape")!=-1

   The application displays a generic warning message, which is defined in the validate.js file, if the user enters invalid data. To change this error message, edit the file and change the contents of the iCustom variable.

Binding JavaServer Page Components to Dynamic Data

---

Dynamic data is represented by merging a JavaServer Page with data obtained by a servlet. JSPs contain placeholders for the incoming data. These placeholders are called RDBM field tags, and the result of a data-accumulation activity, such as a database query, is called a result set. The process by which RDBM field tags are connected with the data returned via ResultSets is called data binding.

The use of any RDBM tag requires a JSP TagLib directive which refers to the RDBM TagLib.

<%@taglib uri="RDBMS" prefix="rdbm" %>

About RDBM Field Tags

RDBM field tags appear as HTML tags on JSPs. They are replaced with the data they describe at runtime. RDBM field tags look like this in the source view:

<rdbm:field name="field_name" query="query_name"></rdbm:field>

RDBM field tags have a type attribute that determines what action the tag performs. The following values for type determine the tag type:

Table 6-5 RDBM Tag Types

RDBM Tag Type	Description
field	Displays a single dynamic value determined by the rdbm field tag, which shows the ResultSet and DataField to display. See .
loop	Repeats the text block for each row in the ResultSet, or a fixed number of times. This tag usually contains one or more RDBM field tags. See.

For more information, see "Using RDBM Tag Library".

About Row Sets

A servlet or JSP can instantiate a row set. Data-bound components in JSPs can be bound to a row set that is instantiated by a servlet.

There are four types of objects you can use as a result set for the purpose of populating a data-bound component:

Table 6-6 ResultSet Types

ResultSet type	Description
DBRowSet	A result set from one or more queries to a relational database.
memRowSet	A result set stored in memory, which does not represent a disk structure such as a row in a table.
session	A standard object (defined in appResource.java) comprising saved session variables.
valIn	A data structure that defines the input parameters to an servlet.

About Data-Binding Properties

Data-binding properties determine which data are displayed in a dynamic component. The following components contain data-bound properties that can be configured to represent data from a servlet for display:

Table 6-7 Components Containing Data-bound Properties

Configured via	Component Type
HTML tab	Data-Bound Image Link, Field, Data-Bound Link, List, Loop
Form tab	CheckBox, Drop-Down List, List Box, Radio Button Group, TextField, Text Area
RDBM	Query, Loop, Field, Parameter, Close, Execute, GoRecord.

There are three standard data-bound properties that together make up a data-bound object, linking a single column of data to a component. The standard data-bound properties are listed in the following table:

Table 6-8 Standard Data-bound Properties

Property	Description
ResultSet	The result set to be displayed.
DataField	The specific column of data in the ResultSet to display. This list is determined by the ResultSet property; only valid fields in the listed ResultSet are shown.
Display Format	An optional format mask that reformats raw data at runtime.

The intersection of one or more data sets with one or more data fields, with optional display formats for each, is called a data expression. You can use a custom data expression to provide multiple combinations of ResultSet, DataField, and display format inside one component. To put it another way, the combination of a ResultSet and DataField (with optional format) is a data expression with only one value.

The data-binding part of a data expression is identified by the notation ResultSet.DataField. For example, valIn.LastName identifies the ResultSet "valIn" and the DataField "LastName".

Output formatting is ignored for valIn, valOut, and session variables.

The Drop-Down List, List Box, and Radio Button Group components contain a data expression property, which overrides the DataField and Display Format properties if the ResultSet property is blank:

Table 6-9 Data Expression Property

Property	Description
Label Expression or Item Expression	An expression that organizes multiple combinations of ResultSet, DataField, and Display Format with arbitrary static text so that multiple fields can be displayed in one component.

Displaying a Single Field of Data

A single field of data can be displayed with a rdbm field tag. The tag's query attribute specifies the ResultSet and name that identify the field to display.

The Label component defines a single rdbm field tag with its ResultSet, name, and optional Display Format properties. Other components that use a single rdbm field tag are: Data-Bound Image Link, Data-Bound Link, CheckBox, TextField, and Text Area.

To display multiple fields of data from the same row, use multiple instances of the same component. For example, to display the fields firstName, lastName, and email, all from the valIn result set, you can use three different Label components in a row, as in the following sample from Layout view:

Displaying Single Columns of Data

You can associate a component with a single field of dynamic data by performing the following steps:

1. Select the component you want to associate with dynamic data.

   If the data occurs on multiple rows (in other words, if you are populating a multiple-item component where the items come from the same field of multiple rows in a ResultSet), this component should be set in a loop. See "Using the Loop Component to Display Rows of Data."

2. Select the ResultSet property in the Properties window.

3. Click the custom property editor button and select a ResultSet.

4. Note that some components have more than one result set property, as in the List Box component where the Options result set gathers all the options to be displayed and the optional Selection result set specifies the one to be the initial selection.

5. Click OK to return to the Properties window.

6. Choose a DataField object for the current data set by selecting a field from the drop-down box in the DataField property.

   The Drop-Down List, List Box, and Radio Button Group components have more than one possible DataField. The Options ResultSet offers both a Labels DataField, from which you select the label to be displayed on the page, and an Items DataField, from which you select the value to be submitted with the form. These data correspond because they are chosen from the same row in the data set. Follow this step for each DataField property.

7. To choose a DataField for display, click the DataField property definition and select an item from the drop-down box.

8. If you want to apply a format mask to the field, adjust the format mask by selecting the Display Format property definition and clicking the custom property editor icon.

Displaying Multiple Columns of Data

You can associate the Drop-Down List, List Box, or Radio Button Group components with multiple dynamic fields, even from multiple result sets. For example, you might want a set of radio buttons to show two fields from a data set, such as a name and an ID number, like this:

You must construct a data expression, because this construction is not possible by dynamically selecting only a single field using the ResultSet and DataField properties.

To create a data expression, select the Label Expression or Item Expression property and click the custom property editor button.

Note that complex data expressions can be used to populate iterative lists, as with the single-field data expressions described in "Displaying Single Columns of Data".

Displaying Multiple Rows of Data

Multiple rows of data can be displayed by using an RDBM loop tag as a container for other tags that display each field. The loop tag repeats its text block for each row in the specified data set, or, if specified, a maximum number of times and/or strings with a specified row. The tag's query attribute specifies the data set over which the tag's contents iterate.

The Loop component defines a single RDBM loop tag. Other components can be inserted into a loop component to display the data. Several other components enable you to display one or more fields of data iteratively, including List, Drop-Down List, List Box, and Radio Button Group.

Using the Loop Component to Display Rows of Data

The Loop component defines a single RDBM loop tag with its ResultSet, and Max Rows. The loop repeats itself for each row of data, up to a maximum number of rows determined by the Max Rows property (which corresponds to the max attribute).

Using Loops as Table Rows

The Loop component defines a RDBM loop tag but does not create an HTML table. you can insert the loop tag as a row in an HTML table to make the loop a table.

You can also insert a RDBM loop tag as a row in an HTML table as follows:

1. Right-click on a table row and choose the Table drop-down menu.

2. Choose Add Loop to make this table row a loop.

3. You can then insert other components into the loop.

   The contents of the loop repeat according to the loop's properties.

For example, if you have a ResultSet called states with a DataField called capital, you could display its contents in a table row with the following steps:

1. Drag the Table component onto your JSP.

2. Select a row in the table and click the right mouse button.

3. Choose Loop and then choose Add Row Loop from the sub-menu.

   The row becomes a loop.

4. Set the loop's ResultSet (query) property to states.

5. Drag the Label component into the new loop.

6. Set the Label's ResultSet property to states, and the DataField property to capital.

   The loop creates a new table row at runtime for each row of data in states, and the Label component displays the capital field for each row.

To remove a loop, select the row containing the loop you want to remove, click the right mouse button, and choose Delete Loop from the Table submenu.

Using Multiple Loops in a JSP

If you have more than one explicit loop in a JSP, you must edit your JSP to reset the result set's cursor to 1 before using your loops.

For example, if you have a loop in your JSP and then add a data bound list, combo box, drop down list, or radio button component before your loop and the component uses the same result set as your loop, you must reset the cursor.

You can reset the cursor by using the RDBM goRecord tag as follows:

<rdbm:goRecord query="your_rowset" start="1"/>

Specifying Custom Formatting for a JSP Field

Often you need to specially format a data field on a JavaServer Page. Although iPlanet Application Server provides a set of formatting masks that you can use to format your output, you may need to do more complex formatting that is not supported directly by the server. For example, if you are displaying the account transactions of a particular customer you might choose to display the transactions with negative values in red.

You can write custom Java code to format data that is returned by result sets for presentation in JSPs. To do so, perform the following steps:

1. Open the JSP with the field you want to format.

2. Select the field you want to format.

3. From the Properties window, open the property editor dialog box for the Display Format property.

4. Select the Custom option for formatting.

5. Specify the name of the Java method that will be used to format the data field.

   You must use a method that is implemented by a RowSet subclass. By default, iPlanet Application Server will generate code for a new RowSet method with the name you specified in this step. Alternatively, you can choose from a list of methods that currently exist in your servlet.

Using RDBM Tag Library

---

The query family of tags support declarative declarations of RowSets in a JSP page, along with loops for looping through result-sets and a display tag for displaying column values.

---

Note	The use of any RDBM tag requires a JSP TagLib directive which refers to the RDBM TagLib.

---

1. <rdbm:useQuery id="export_name" scope="[page|request|session|application]" command="select * from..." queryFile="foo.gxq" queryName="firstQuery" execute="[true|false]" dataSourceName="jdbc/..." url="odbc:...">...</rdbm:useQuery>

2. <rdbm:param query="query-declaration-export-name" name="name-of-parameter" value="value" bindOnLoad="[true|false]" type="[String|Int|Double|Float|BigDecimal|Date|Boolean|Time|Timestamp" format="java-format-string for dates">value</rdbm:param>

3. <rdbm:loop id="export_name" scope="[page|request|session|application]" query="query-declaration-export-name" start="[request-parameter-name|request-attribute-name|last|constant]" max="integer-maximum-number-of-rows"execute='{true|false]">...</rdbm:loop>

4. <rdbm:field query="query-declaration-export-name" name="field name" format="format for doubles" urlEncode="{false/true}">default value</rdbm:field>

5. <rdbm:close resource="query-declaration-export-name"/>

6. <rdbm:execute query="query-declaration-export-name"/>

7. <rdbm:goRecord query="query-declaration-export-name" execute="{false/true}"start="[request-parameter-name|request-attribute-name|last|constant]">default start</rdbm:goRecord>

useQuery Tag

The useQuery tag declares a use of a result-set. It instantiates a TYPE_SCROLL_INSENSITIVE RowSet. The useQuery tag allows the tool to understand what query is being made, and thereby, what fields are available.

If the result set is already in the scope the useQuery wants to save to, the body of the tag is skipped. Although the RowSet is created, nothing is done with the created RowSet. Some performance gain is seen by lazily creating the RowSet and saving the command and connection until the tag knows the RowSet is needed.

If the result-set does not already exist, the created RowSet is exported using the id attribute of the useQuery tag at the specified scope, which defaults to request.

Either the command specified is used, or a query located in the queryFile is loaded. The name of the loaded query is either the name located in the queryName attribute, or, if it is unspecified, the value of the tag's id attribute.

Once the rowset is initialized, it may be executed if the execute tag is specified. You must execute a query if you want to use the field tag outside of a loop. This displays only the first record in any query.

The two attributes queryFile and queryName work in conjunction. The queryFile locates the query file. If the value of the attribute is a relative file specification, then the file is looked up in the RDBMS.path.query path. This path should be specified as a System property (on UNIX colon separators, on NT semicolon separators) directories. If this variable is not set, then the iAS-specific RDBM.path.query property is used. The file is not located relative to the JSP itself. The query file can be created using the File menu Add Query submen.

Additionally, because RowSets have numbered parameters, the useQuery tag exports Dictionary mapping parameter names (as specified in the command attribute, or in the query file) to Integer offsets as an attribute in the same scope as the RowSet using the value of the id attribute prepended to "._params" as the name for the attribute. This makes setting parameters after the RowSet is declared and before it is executed possible.

Param Tag

The Param tag sets a parameter on a RowSet. The name of the parameter can either be an index or the actual name of the parameter as saved in the Dictionary. If bindOnLoad is true, the parameter is set before the command is set on the RowSet.

---

Note	bindOnLoad parameters must exist in the body of the useQuery tag before any non-bindOnLoad parameters.

---

The value of the parameter is either the value stored in the value attribute, or the contents of the param tag's body. Because JSP1.1 tags don't generally nest (<%= ... %> being the notable exception), the only way to bind a parameter to a value from another query is to place a field tag within the body of a parameter tag and have the parameter tag use its body as the value. This is why you can place the value in the body of the tag.

Param tags may exist within the useQuery tag, in which case they set the parameters directly against their parent query, or elsewhere, probably before a loop tag re-executes the RowSet, in which case the parameter is set on the RowSet that the useQuery tag exported.

Loop Tag

The loop tag loops through the contents of a ResultSet. The query attribute is used to locate the ResultSet or an enclosing useQuery tag. The start attribute is used to indicate the starting position of the loop. Start may either refer to a parameter, or to an attribute, which is looked up using PageContext.findAttribute() or a constant Integer value. The value then indicates which record number to start on, or "last", which will cause the RowSet to scroll to the end, and then back max rows. The max attribute is used to indicate the maximum number of records to display.

Once the loop is finished, the loop tag exports two values -- the number of records that were requested for display (max) and the number of records which were actually displayed. These are saved in attributes using the patterned name id_query_max and id_query_output, respectively. The scope attribute indicates where these attributes are persisted.

If execute is specified, the RowSet is executed before looping begins.

Field Tag

The field tag displays a particular column in the ResultSet. The query attribute locates the enclosing useQuery tag or a previous useQuery tag's exported ResultSet. The name attribute identifies the column name to display. The format attribute allows formating of Strings, numbers, or dates into the appropriate type. The Attribute urlEncode can be used to encode the strings. If the column is null, the body of the field tag is output.

Close Tag

The close tag releases resources back to the system. The resource attribute locates the exported query resource (ResultSet) and calls close() on it.

Execute Tag

The execute tag executes the identified query.

goRecord Tag

The goRecord tag optionally executes the specified query and moves the ResultSet to the record indicated by the start attribute. Start can refer to a parameter, an attribute, or a constant. If the start attribute is last,the result-set is moved to the last record.

Example

The following tags produce the displayed output.

<HTML>
<BODY>
<h2>Now let us see</h2>
<rdbm:useQuery id="a" queryFile="queries.gxq" dataSourceName="jdbc/cdx">
</rdbm:useQuery>
<rdbm:useQuery id="b" queryFile="queries.gxq" dataSourceName="jdbc/cdx">
</rdbm:useQuery>

<table border=1 cellPadding=3>
   <tr>
   <th>name</th>
   <th>phone</th>
   <th>Titles Owned</th>
   </tr>

   <rdbm:loop id="loop1" query="a" max="5" execute="true">

      <tr>
      <td><rdbm:field query="a" name="name"/></td>
      <td><rdbm:field query="a" name="phone"/></td>
      <td><rdbm:param query="b" id="owner" type="Int">
         <rdbm:field query="a" name="id"/></rdbm:param>

         <table border=1 cellPadding=3 width="100%">
         <tr>
         <th>title</th>
         <th>price</th>
         <th>artist</th>
         </tr>

         <rdbm:loop id="loop2" query="b" max="5" execute="true">

         <tr>
         <td><rdbm:field query="b" name="title"/></td>
         <td><rdbm:field query="b" format="$#,###.00"
            name="price"/></td>
         <td><rdbm:field query="b" name="artist"/></td>
         </tr>

         </rdbm:loop>

</table
</td>
</tr>

</rdbm:loop>

</table>

<rdbm:close resource="a"/>
<rdbm:close resource="b"/>

</BODY>
</HTML>

Numeric Format Characters

Table 6-10 Numeric Format Characters 

Character	Meaning	Example Data	Example String	Example Result
#	Unfilled digit placeholder. Replaced by numeric digits in the data. If the data to format has fewer digits than the format string, the empty places are not filled. The output can be shorter than the format string.	679.649 700	#####.## $#,###.00	679.64 $700.00
0	Zero-filled digit placeholder. Replaced by numeric digits in the data. If the data to format has fewer digits than the format string, the empty places are filled with zeros. The output is always at least as long as the format string. When placed to right of decimal point, indicates precision. Data is rounded if necessary.	679.649 679.649 700	0000.00 00### $000.00	0679.65 00679 $700.00
,	Thousands separator. A separator character will appear between every three digits to the left of the decimal point in the output data.	1234	0,000	1,234
.	Decimal separator. A decimal point character will appear between the whole and fractional parts of the output data.	679.649 700	000.00 $#,###.00	679.65 $700.00
;	Separates a pair of formats. The first format is used for positive numbers, the second for negative numbers.	23 -66	##;(##) ##;(##)	23 (66)
Literals such as $ + - ( ) and space characters	Any character in the format string that is not a special character will appear in the output data exactly as typed. If using parentheses, always use matched pairs.	5552365 69100 123	###-#### $0,000 0 0 0	555-2365 $69,100 1 2 3

Date/Time Format Characters

Table 6-11 Date/Time Format Characters 

Character	Meaning	Example Data	Example String	Example Result
D	Day of the month, with no leading zero.	1/1/2020	M-D-YY	1-1-20
DD	Day of the month, with leading zero.	1/1/2020	MM-DD-YY	01-01-20
DDD	Day of the week, abbreviated.	7/4/1996	DDD	Thu
DDDD	Full day of the week.	7/4/1996	DDDD	Thursday
M	Number of the month, with no leading zero.	1/1/2020	M-D-YY	1-1-20
MM	Number of the month, with leading zero.	1/1/2020	MM-DD-YY	01-01-20
MMM	Name of the month, abbreviated.	1/1/2020	MMM	Jan
MMMM	Full name of the month.	1/1/2020	MMMM	January
y	Number of the day in the year (1-366).	1/1/2020	y	1
YY	Last 2 digits of the year.	1/1/2020	M-D-YY	1-1-20
YYY or YYYY	All 4 digits of the year.	1/1/2020	M-D-YYYY	1-1-2020
h	Hour from 1-12, with no leading zero.	8:05 pm	h:mm	8:05
hh	Hour from 1-12, with leading zero.	8:05 pm	hh:mm	08:05
H	Hour from 1-24, with no leading zero.	8:05 pm	H:mm	20:05
HH	Hour from 1-24, with leading zero.	3:00 am	HH:mm	03:00
m	Minute, with no leading zero.	3:09 am	h:m	3:9
mm	Minute, with leading zero.	3:09 am	h:mm	3:09
s	Seconds, with no leading zero.	3:09 am	h:m:s	3:9:0
ss	Seconds, with leading zero.	5:07:02 am	hh:mm:ss	05:07:02
AM/PM	Adds letters AM or PM after the date/time data to indicate morning or afternoon/evening hours.	5:07:02 am	h:mm AM/PM	5:07 AM
Literals such as / - : and space characters	Any character in the format string that is not a special character will appear in the output data exactly as typed.	1/1/2020 8:05 am	m-d-yy h:m:s	1-1-20 8:5:0