Appendix A   Component Reference


This appendix describes all components available on the palette.

About Components

---

Components are reusable objects that you can place on an HTML page or JavaServer Page to perform a certain task. The behavior and appearance of components are determined by their properties.

Components are Java objects called Editor Beans that generate the required HTML and JavaScript code, depending on the environment into which they are dropped. For example, if you drop a form component like PushButon onto a blank page, a new form is automatically created, though the same component uses an existing form if dropped onto one. Note that some of the code generated by Editor Beans should not be edited; see Using Source View.

Data-Bound Properties

Some components have properties which allow their behavior and appearance to be controlled at run-time by a servlet or JSP tag (rdbm:field). These are called data-bound properties. They only appear on components that have been inserted into a JSP, as they serve no purpose on a static HTML page.

The following components contain data-bound properties that can be configured to represent data returned from a servlet or JSP tag for display:

Table A-1 Data Bound Properties 

HTML tab	Data-Bound Image Link, Data-Bound Link, List
Form tab	CheckBox, Drop-Down List, List Box, Radio Button Group, TextField, Text Area
RDBM tab	RDBM Taglib Directive, Query, Loop, Field, Param, Close, Execute, GoRecord

Target Window

Some components provide hypertext links to load other URLs or called servlets. These components can display the resulting page in the current window or in another window or frame by setting the Target property.

The following values are valid for the Target property:

Table A-2 Target Property Valid Values

_self	Display in the same frame or window.
_top	Display in the full body of the window, overriding any existing frames.
_blank	Display in a new blank window.
_parent	Display in the same frameset as the current link, removing any child frames.
none	Display in current window. Same as _self.
custom	Custom target.

Consult an HTML reference for more details.

Palette Tabs

Components appear by default on the following palette tabs:

HTML tab.

Data-Bound Link	Hypertext link
Image	HTML image
Data-Bound Image Link	HTML image that serves as a hypertext link
DropDown Link	Hyperlinked combo-box navigation widget
Link Target	Named hypertext target
Horizontal Line	Horizontal rule (<hr>)
Table	HTML table
Loop	Data-bound repeating container
List	Data-bound list

Form tab.

Form	HTML form container
Push Button	HTML form Submit or Reset button
Text Field	HTML form text field
Text Area	HTML form text field, multiple lines
List Box	HTML form list box
Drop-Down List	HTML form drop-down selector list
Radio Button Group	HTML form radio-button
CheckBox	HTML form checkbox
Custom Script	Custom script

JSP tab.

JSP Taglib Directive	Defines a tag library and prefix for the custom tags used in the JSP page.
JSP Include Directive	Includes a file or text code when the JSP page is translated.
JSP Page Directive	Defines attributes that apply to an entire JSP page.
JSP Expression	Contains an expression valid in the scripting language used in the JSP page.
JSP Scriptlet	Contains a code fragment valid in the page scripting language.
JSP Declaration	Declares a variable or method valid in the scripting language used in the JSP page.
JSP Include	Sends a request to an object and includes the result in a JSP file.
JSP Forward	Forwards a client request to an HTML file, JSP file, or servlet for processing.
JSP UseBean	Locates or instantiates a Bean with a specific name and scope.
JSP SetProperty	Sets a property value or values in a Bean.
JSP GetProperty	Gets a property value or values in a Bean.
JSP Param	Provides key/value information tothe JSP Include, JSP Forward, and JSP Plugin tags.
JSP ParamList	Provides a grouping of JSP Param tags.
JSP Plugin	Downloads a Java plugin to the client web browser to execute an applet or Bean.
JSP Fallback	Indicates the content to be used by the client browser if the plugin cannot be started.

RDBM tab.

Taglib Directive	Defines a tag library and prefix for the custom tags used in the JSP page.
Query	Declares a use of a ResultSet.
Loop	Loops through the contents of a ResultSet.
Field	Displays a particular column in the ResultSet.
Param	Sets a parameter on a RowSet
Close	Releses resources back to the system.
Execute	Executes the identified query.
GoRecord	Optionally executes the specified query and moves the ResultSet to the indicated record.

Components

---

The following sections describe each component in the iPlanet Application Builder JSP Palette tab.

CheckBox

The CheckBox component provides a form field in the form of a checkbox. If the box contains a check when the form is submitted, the field's value (see the Value property below) is submitted with the form. Application users can check or uncheck the box by clicking on it at runtime.

This component can optionally be bound to output data from a servlet. For more information, see Binding JavaServer Page Components to Dynamic Data.

This component resides on the Form tab by default.

Table A-3 Form Tab Default Components

Property	Values	Description
(Name)	String	Name of this component.
Checked	true or false	Whether the box is checked by default.
DataField	Field in ResultSet	Name of the data set field submitted with the form. If the box is checked, the argument DataField="value" is submitted with the form (see the Value property below).
ResultSet	Row set	Name of the servlet ResultSet used to populate this component. Adding data to this field causes the DataField and Display Format properties to appear.
Display Format	Format	Optional format mask for dynamic data.
Value	String	Value of field, submitted with form if box is checked. This field is entered as VALUE="value" in the HTML code representation of this component.

Custom Script

The Custom Script component provides a framework for you to develop your own custom scripts in JavaScript. Drop this component onto your page and then edit it by clicking the Source tab.

Data-Bound Image Link

The ImageLink component is similar to an Image component, except that it also functions as a hypertext link to another page or to a servlet.

This component can optionally be bound to the results of a query.

Table A-4 Image Link Components 

Property	Values	Description
(Name)	String	Name of this component.
Alignment	ABSBOTTOM, ABSMIDDLE, BOTTOM, LEFT, MIDDLE, RIGHT, TEXTTOP, BASELINE, or TOP	Image alignment with respect to surrounding text. For details, consult an HTML reference.
Alternate Text	String	Text which appears instead of the specified image on browsers that do not support images. This string often appears as bubble help when the cursor hovers over the image. Not used when data-bound.
Alternate Text DataField	Field in ResultSet	Name of the field in the data set to display as alternate image text.
Border	Integer	Width of a border surrounding the image, in pixels.
ResultSet	Row set	Name of the result set used to populate this component. Adding data to this field causes the DataField properties to appear.
Destination URL	URL	Destination of this hyperlink. This URL is loaded when the user clicks the image.
Height	Integer	Height of the image, in pixels. Specifying this property allows your page to load faster.
Horizontal Margin	Integer	Indentation from the left of the containing page, frame, or table cell to the left side of the image, in pixels.
Image Source	URL	Location of the source file for this image. Not used when data-bound.
Image Source DataField	Field in ResultSet	Name of the field in the ResultSet to display as the location of the source file for this image.
Target	Target Window	Name of the window or frame where the results of this hyperlink should appear.
Vertical Margin	Integer	Indentation from the top of the containing page, frame, or table cell to the top of the image, in pixels.
Width	Integer	Width of the image, in pixels. Specifying this property allows your page to load faster.

Data-Bound Link

The Link component provides a hypertext link to another page or to a servlet.

This component can optionally be bound to the results of a query. For more information, see Binding JavaServer Page Components to Dynamic Data.

Table A-5 Data Bound Output Data

Property	Values	Description
DataField	Field in row set	Name of the field in the data set to display as link text.
ResultSet	Row set	Name of the result set used to populate this component. Adding data to this field causes the DataField and Display Format properties to appear.
Destination URL	URL	Destination of this hyperlink. This URL is loaded when the user clicks the link.
Display Format	Format	Optional format mask for dynamic data.
Link Text	String	Text that appears on the screen. This text forms the basis of the hyperlink, meaning that it lies inside the <a> container. This property is not used when the component is data-bound.
Target	Target Window	Name of the window or frame where the results of this hyperlink should appear.

DropDownLink

The DropDownLink component defines a set of possible hypertext links in a drop-down selectable list. When an item is selected, the browser then loads the page for that item.

Table A-6 Drop Down Link Properties

Property	Values	Description
(Name)	String	Name of this component.
Items	Component-defined list entries	A list of entries for the drop-down list, including the label to display and the destination URL where the label points. You must use the custom property editor.

Drop-Down List

The Drop-Down List component provides a list of values, of which one can be selected at run-time from a drop-down list box.

This component can optionally be bound to the results of a query.

Note that you must set two data bindings, including a set of items (Items DataSet) and the item selected initially (Selection ResultSet). To set multiple data fields per option, use Labels Expression and Selection Criteria.

Table A-7 Drop Down List Properties 

Property	Values	Description
(Name)	String	Name of this component.
Items	Component-defined list entries	A list of entries for the list. For best results, use the custom property editor. This property is not used when the component displays dynamic data (see the Items ResultSet property).
Items ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field enables all of the data binding Labels DataField, Labels Display Format, Expression, Maximum Items, Selection DataField, and Selection ResultSet properties.
Labels DataField	Depends on Items ResultSet	Name of the field in the Items ResultSet to display in the list. Corresponds to Values DataField, which is the value submitted with the form.
Labels Display Format	Format	Optional format mask for dynamic data.
Labels Expression	expression	Data-bound multiple-value expression for labels. The properties Labels DataField and Labels Display Format are only used if this property is blank. For best results, use the custom property editor.
Maximum Items	Integer	The maximum number of items to be displayed.
Multiple	True or false	True if the user can select multiple entries; false if only one entry selection is allowed.
Selection Criteria	Java expression	Expression that identifies the item selected initially. The Selection ResultSet and Selection DataField properties are only used if this property is blank.
Selection DataField	Field in row set	Name of the field in the ResultSet that identifies the item that was initially selected.
Selection ResultSet	Row set	Name of the servlet result set used to identify the item that was initially selected.
Size	Integer	Number of items visible at a time.
Values DataField	Depends on Items ResultSet	Name of the field in the Items ResultSet to match as a value to the associated Labels DataField and submitted with the form.

Field

The Field component defines an element for displaying dynamic text. For example, this component could reference a query which looks up a user's first name based on a provided ID and password; the resulting name is then provided to the page and displayed on the screen.

This component must be bound to output data from a useQuery.

Table A-8 Field Properties

Property	Values	Description
DataField	Field in row set	Name of the field in the row set to display as normal page text.
ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field causes the DataField and Display Format properties to appear.
Display Format	Format	Optional format mask for dynamic data.

Form

The Form component is the container for HTML form elements. This component holds components for data input, as well as other page elements as necessary.

Note that the Form component itself displays nothing on the page at runtime. You must add other components to a form, including a way to submit the form, such as the PushButton component.

Table A-9 Form Properties 

Property	Values	Description
(Name)	String	Name of this component.
Action	URL	Action to perform when the form is submitted, e.g. when the Submit button is clicked. The action is specified in the form of a web address or servlet. For best results, use the custom property editor.
Encoding	application/x-www-form-urlencoded or multipart/form-data	MIME encoding for this component.
Method	Get or Post	Form submission method. For more information, consult an HTML reference.
Target	Target Window	Name of the window or frame where the results of the form submission appear.

Horizontal Line

The Horizontal Line component places a horizontal rule (<hr>) on your page.

Table A-10 Horizontal Line Properties 

Property	Values	Description
Alignment	CENTER, LEFT, or RIGHT	Align to the center, left, or right side of the containing page, frame, table cell, or list item.
No 3-d Shading	true or false	If false, a dropped shade is applied to the line.
Thickness	Integer	Vertical thickness of the line, in pixels.
Width	Integer or Percentage	Width of the line expressed as either a number of pixels or a percentage of the containing page, frame, table cell, or list item. A value of 100% fills the container horizontally.

Image

The Image component defines a graphic image in GIF or JPG format. Note that this component is not data-bound. For a dynamic version of this component, use Data-Bound Image Link.

Table A-11 Image Properties 

Property	Values	Description
(Name)	String	Name of this component.
Alignment	ABSBOTTOM, ABSMIDDLE, BOTTOM, LEFT, MIDDLE, RIGHT, TEXTTOP, or TOP	Image alignment with respect to surrounding text. For details, consult an HTML reference.
Alternate Text	String	Text which appears instead of the specified image on browsers that do not support images. On browsers that do support images, this string often appears as bubble help when the cursor hovers over the image.
Border Width	Integer	Width of a border surrounding the image, in pixels.
Height	Integer	Height of the image, in pixels, or the percentage of page height. Specifying this property allows your page to load faster.
Horizontal Margin	Integer	Indentation from the left of the containing page, frame, or table cell to the left side of the image, in pixels.
Is Map	True or false	Specify whether this image is a clickable image map. For more information, consult an HTML reference.
Low Res. Source	URL	Source for a low-resolution (often black and white) version of the image. This version loads and displays first, allowing the user to make decisions and continue without waiting for images to download.
Map Name	String	Indicates the name of a server-side image map. For more information, consult an HTML reference.
Source	URL	Location of the source file for this image.
Vertical Margin	Integer	Indentation from the top of the containing page, frame, or table cell to the top of the image, in pixels.
Width	Integer	Width of the image, in pixels, or the percentage of page width. Specifying this property allows your page to load faster.

These events do not appear on the Events tab in the property inspector. To handle an event, edit the component in Source view and add an appropriate argument to the <img> tag. The following example instructs the image to handle the onLoad event by calling imageLoaded():

<IMG SRC="image.gif" ONLOAD="imageLoaded()">

Link Target

The Link Target component defines a named mid-page URL target, specified with the HTML code <a name="name">. You can link to this target with a # separator, with a URL of the form pageURL#name.

Table A-12 Link Target Properties

Property	Values	Description
(Name)	String	Name of this target, used as name above.

List

The List component defines an HTML ordered list <ol> or unordered list <ul>.

This component is intended to be bound to output data from a query. For more information, see Binding JavaServer Page Components to Dynamic Data.

Table A-13

Property	Values	Description
DataField	Field in row set	Name of the field in the row set to display as list items.
ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field causes the DataField and Display Format properties to appear.
Display Format	Format	Optional format mask for dynamic data.
List Type	Itemized	Type of list. List types include: Bulleted - circles (filled bullets) Bulleted - discs (empty bullets) Bulleted - squares Numbered - Arabic (1, 2, 3) Numbered - Roman capitals (I, II, III) Numbered - Roman lowercase (i, ii, iii) Lettered - capitals (A, B, C) Lettered - lowercase (a, b, c)
Maximum Rows	Integer	The maximum number of rows of data to be displayed.

List Box

The List Box component provides a list of values in a form selector box, of which one or more can be selected at run-time.

This component can optionally be bound to the results of a query. For more information, see Binding JavaServer Page Components to Dynamic Data.

Note that you must set two data bindings, including a set of items (Items ResultSet) and the item selected initially (Selection ResultSet). To set multiple row fields per option, use Labels Expression and Selection Criteria.

Table A-14 List Box Properties 

Property	Values	Description
(Name)	String	Name of this component.
Items	Component-defined list entries	A list of entries for the list. For best results, use the custom property editor. This property is not used when the component displays dynamic data (see the Items ResultSet property).
Items ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field enables the Labels DataField, Labels Display Format, Labels Expression, Maximum Items, Selection DataField, Selection ResultSet, and Values DataField properties.
Labels DataField	Depends on Items ResultSet	Name of the field in the Items ResultSet to display in the list. Corresponds to Values DataField, which is the value submitted with the form.
Labels Display Format	Format	Optional format mask for dynamic data.
Labels Expression	expression	Data-bound multiple-value expression for labels. The properties Labels DataField and Labels Display Format are only used if this property is blank. For best results, use the custom property editor.
Maximum Items	Integer	The maximum number of items to be displayed.
Multiple	True or false	True if the user can select multiple entries; false if only one entry selection is allowed.
Selection Criteria	Java expression	Expression that identifies the initially selected item(s). The Selection ResultSet and Selection DataField properties are used if this property is blank.
Selection DataField	Field in row set	Name of the field in the row set to display.
Selection ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field displays the DataField and Display Format properties.
Size	Integer	Number of items visible at a time.
Values DataField	Depends on Items ResultSet	Name of the field in the Items ResultSet to match as a value to the associated Labels DataField and submitted with the form.

Loop

The Loop component represents a repeating row of data from a query. The component replicates itself for each row of data to be displayed. For example, if a Loop component defines a row in an HTML table, at runtime the table contains one row for each row of data.

Note that the Loop component itself displays nothing on the page; it only repeats according to the rules specified by its properties. Insert other components into the tile to display one or more fields in each row.

Table A-15 Loop Properties

Property	Values	Description
Query Name	Row set	Name of the ResultSet used to populate this component.
Scope	page, request, session, or application	Specifies the scope of visibility of the loop
StartRecord	integer	First record to display the result set.
Loop ID	String	Name of the loop with in the scope.

PushButton

The PushButton component defines a button for an HTML form.

Table A-16 Push Button Properties 

Property	Values	Description
(Name)	String	Name of button (submitted with the form)
Button Type	Submit, Reset, Button, or Image	Type of button. Submit button sends the form to the server for processing. Reset button resets all fields to their default values. Button causes the button to perform only the actions specified with the onClick event (useful for creating buttons that do something other than submitting a form). Image is a button that displays a graphic instead of text on a button.
Label	String	Label that appears on the button. Submitted with the form if the Name property is specified.
Image Source	String	URL of the graphic file to display. Only active if the Button type is image.
Image Alignment	LEFT, RIGHT, TOP, ABSMIDDLE, ABSBOTTOM, TEXTTOP, MIDDLE, BASELINE, or BOTTOM	The kind of alignment you want to use for a graphic..

Radio Button Group

The Radio Button Group component defines a radio-style selector switch with two or more entries, for use in a form. Only one selection is allowed.

This component can optionally be bound to the results of a query. For more information, see Binding JavaServer Page Components to Dynamic Data.

Note that you may set two data bindings, including a set of items (Items ResultSet) and the item selected initially (Selection ResultSet). To set multiple data fields per option, use Labels Expression and Selection Criteria.

Table A-17 Radio Button Group Properties 

Property	Values	Description
(Name)	String	Name of this component.
Labels DataField	Depends on Items ResultSet	Name of the field in the Items ResultSet to display as labels for the radio buttons, matched with Values DataField as the value submitted with the form.
Labels Display Format	Format	Optional format mask for dynamic data.
Labels Expression	expression	Data-bound multiple-value expression for labels. The properties Labels DataField and Labels Display Format are only used if this property is blank. For best results, use the custom property editor.
Maximum Items	Integer	The maximum number of items to be displayed.
Items	Component-defined list entries	A list of entries for the radio button group. For best results, use the custom property editor. This property is not used when the component displays dynamic data (see the Items ResultSet property).
Items ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field causes the Labels DataField, Labels Display Format, Labels Expression, Maximum Items, Selection DataField, Selection ResultSet, and Values DataField properties to appear.
Selection Criteria	Java expression	Expression that identifies the radio button selected initially. The Selection ResultSet and Selection DataField properties are used if this property is blank.
Selection DataField	Field in ResultSet	Name of the field in the row set used to determine which radio button is selected by default.
Selection ResultSet	Row set	Name of the ResultSet used to populate this component. Choosing a data set in this field causes the DataField and Display Format properties to appear.
Values DataField	Depends on Items ResultSet	Name of the field in the Items ResultSet to match as a value to the associated Labels DataField and submitted with the form.

Table

The Table component places a table on the page.

While the Table component itself is not data-bound, its contents can be bound to output data from a servlet. Each row of a table is defined by a TR (table row) tag. Each cell is defined by a TD (table data) tag. Right click on a cell to insert or delete rows or cells. For more information, see Binding JavaServer Page Components to Dynamic Data. In particular, you can use the Loop component to populate rows of the table dynamically and the Field component to populate individual cells (such as header cells).

Table A-18 Table Properties

Property	Values	Description
Align	left, right or center	Alignment of table in relation to the containing page, frame, or table cell.
Background Color	Color	Table background color.
Border	Integer	Width of the border surrounding each cell, in pixels. Set to 0 for no border.
Cell Padding	Integer	Distance between cell border and contents, in pixels.
Cell Spacing	Integer	Distance between individual cells, in pixels.
Columns	Integer	Number of columns in the table, used to speed page layout.
Height	Integer or Percentage	Minimum table height, in pixels or percentage of visible screen.
Horizontal Margin	Integer	Horizontal margin between table and surrounding text, in pixels.
Vertical Margin	Integer	Vertical space between table and surrounding text, in pixels.
Width	Integer or Percentage	Table width, in pixels or expressed as a percentage of the width of the containing page, window, or cell.

Text Area

The Text Area component displays text and enables multiple-line text entry in a form.

This component can optionally be bound to the results of a query. For more information, see Binding JavaServer Page Components to Dynamic Data.

This component can optionally be validated when a value is entered. For more information, see Validating Data Entered on a Form in "Creating Presentation Layout."

Table A-19 Text Area Properties

Property	Values	Description
(Name)	String	Name of this component.
DataField	Field in row set	Name of the field in the row set to display as the value of the text area initially.
ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field causes the DataField and Display Format properties to appear.
Display Format	Format	Optional format mask for dynamic data.
Height	Integer	Height of visible text area, in lines.
Validation	Itemized	Type of validation to perform, or (none) to disable this feature. If (Custom), use the Validation Expression property to perform validation.
Validation Expression	JavaScript code	Custom validation expression. Use if the Validation property is set to (Custom).
Value	String	Initial default value of the component.
Value Required	true or false	If true, form submission is rejected until a value is entered. Combine with Validation to ensure proper values.
Width	Integer	Width of text area, in characters.
Wrapping	OFF, HARD, or SOFT	Method for handling input lines longer than the width of the component. HARD inserts a newline at the end of each line, SOFT indicates that the value is to be treated as one line, and OFF disables text wrapping altogether.

TextField

The TextField component displays text and enables a single line of text entry on a form.

This component can optionally be bound to the results of a query. For more information, seeBinding JavaServer Page Components to Dynamic Data.

This component can optionally be validated when a value is entered. For more information, see Validating Data Entered on a Form in "Creating Presentation Layout."

Table A-20 Text Field Properties 

Property	Values	Description
(Name)	String	Name of this component.
DataField	Field in row set	Name of the field in the row set to display as the value of the text field initially.
ResultSet	Row set	Name of the ResultSet used to populate this component. Adding data to this field causes the DataField and Display Format properties to appear.
Display Format	Format	Optional format mask for dynamic data.
Length	Integer	Width of text area, in characters.
Maximum Length	Integer	Number of characters allowed in the input. If greater than Length, the cursor scrolls horizontally while text is being entered that exceeds Length.
Type of field	TEXT, PASSWORD, or HIDDEN	Nature of the text in this field. TEXT indicates plain text, and PASSWORD indicates that the value is obscured (characters appear as asterisks). HIDDEN indicates that the field is not visible at runtime in the browser.
Validation	Itemized	Type of validation to perform, or (none) to disable this feature. If (Custom), use the Validation Expression property to perform validation.
Validation Expression	JavaScript code	Custom validation expression. Use if the Validation property is set to (Custom).
Value	String	Initial default value of the component.
Value Required	True or false	If true, form submission is rejected until a value is entered. Combine with Validation to ensure proper values.