Previous Next Contents Index


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 PushButton onto a blank page, it is set in a new form, 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. 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 for display:

HTML tab
Data-Bound Image Link, Label, Data-Bound Link, List, Tile
Form tab
CheckBox, Drop-Down List, List Box, Radio Button Group, TextField, Text Area

See "Binding JavaServer Page Components to Dynamic Data" for more information on data-bound components.

Events
Some components handle some browser events using client-side JavaScript. Events handled by a given component are listed with that component. For information on browser events, see "Handling Browser Events".

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:

_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. More information about HTML and JavaScript can be found on the Netscape DevEdge web site.

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

DropDownLink
Hyperlinked combo-box navigation widget

Link Target
Named hypertext target

Horizontal Line
Horizontal rule (<hr>)

Label
Data-bound label

Table
HTML table

Tile
Data-bound repeating container

List
Data-bound list

Form tab.

Form
HTML form container

PushButton
HTML form Submit or Reset button

TextField
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


Components
This section identifies the following components:

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.

Property
Values
Description
(Name)
String
Name of this component, addressable in the parameter list for the calling servlet.
Checked Expression
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.

This component responds to the following browser events:

Event
Occurs when
onBlur
Input focus is removed from the element
onClick
Left mouse button is clicked on component
onFocus
Input focus is given to the element

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.

You can find more information about client-side JavaScript on the Netscape DevEdge web site.

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 output data from a servlet. For more information, see "Binding JavaServer Page Components to Dynamic Data".

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 servlet query tag used to populate this component. Adding data to this field causes the DataField property 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.

This component responds to the following browser events:

Event
Occurs when
onClick
Left mouse button is clicked on component
onMouseOver
Cursor passes into component boundary
onMouseOut
Cursor passes out of component boundary

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

This component can optionally be bound to output data from a servlet. For more information, see "Binding JavaServer Page Components to Dynamic 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 servlet query tag 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.

Event
Occurs when
onClick
Left mouse button is clicked on component
onMouseOver
Cursor passes into component boundary
onMouseOut
Cursor passes out of component boundary

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.

Property
Values
Description
(Name)
String
Name of this component, addressable in the parameter list for the calling servlet.
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.

This component responds to the following browser events:

Event
Occurs when
onBlur
Input focus is removed from the element
onChange
Selected value is changed
onFocus
Input focus is given to the element

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 output data from a servlet. 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 DataSet) and the item selected initially (Selection ResultSet). To set multiple data fields per option, use Labels Expression and Selection Criteria.

Property
Values
Description
(Name)
String
Name of this component, addressable in the parameter list for the calling servlet.
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 servlet ResultSet used to populate this component. Adding data to this field enables the DataField and Display Format 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
GX 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.

This component responds to the following browser events:

Event
Occurs when
onBlur
Input focus is removed from the element
onChange
Selected value is changed
onFocus
Input focus is given to the element

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.

Property
Values
Description
(Name)
String
Name of this component.
Action
URL
Action to perform 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.

This component responds to the following browser events:

Event
Occurs when
onReset
Form is reset (RESET button is clicked)
onSubmit
Form is submitted (SUBMIT button is clicked)

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

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.

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.

This component responds to the following browser events:

Event
Occurs when
onLoad
Page or window loads into browser memory
onAbort
Page loading is aborted by the user
onError
Page loading encounters an error

Note. 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()">
Label
The Label component defines an element for displaying dynamic text. For example, this component could reference a servlet which looks up a user's first name based on a provided ID and password; the resulting name is then provided to the page by and displayed on the screen.

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

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 servlet query tag 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.

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.

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 servlet. For more information, see "Binding JavaServer Page Components to Dynamic Data".

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 servlet query tag 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:
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 output data from a servlet. 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.

Property
Values
Description
(Name)
String
Name of this component, addressable in the parameter list for the calling servlet.
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 servlet used to populate this component. Adding data to this field enables the DataField and Display Format 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
GX 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 radio button selected initially. 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 servlet query tag 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.

This component responds to the following browser events:

Event
Occurs when
onBlur
Input focus is removed from the element
onChange
Selected value is changed
onFocus
Input focus is given to the element

PushButton
The PushButton component defines a button for an HTML form.

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.
Image Alignment
LEFT,
RIGHT,
TOP,
ABSMIDDLE,
ABSBOTTOM,
TEXTTOP,
MIDDLE,
BASELINE, or
BOTTOM
The kind of alignment you want to use for a graphic..

This component responds to the following browser events:

Event
Description
onBlur
Input focus is removed from the element
onClick
Left mouse button is clicked on component
onFocus
Input focus is given to the element

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 output data from a servlet. 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.

Property
Values
Description
(Name)
String
Name of this component, addressable in the parameter list for the calling servlet.
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
GX 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 servlet used to populate this component. Adding data to this field causes the DataField and Display Format 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 servlet query tag 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.

This component responds to the following browser events:

Event
Occurs when
onBlur
Input focus is removed from the element
onClick
Left mouse button is clicked on the element
onFocus
Input focus is given to the element

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 Tile component to populate rows of the table dynamically and the Label component to populate individual cells (such as header cells).

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 output data from a servlet. 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.

Property
Values
Description
(Name)
String
Name of this component, addressable in the parameter list for the calling servlet.
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 servlet query tag 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.

This component responds to the following browser events:

Event
Occurs when
onBlur
Input focus is removed from the element
onChange
Selected value is changed
onFocus
Input focus is given to the element

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

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 can optionally be validated when a value is entered. For more information, see Validating Data Entered on a Form.

Property
Values
Description
(Name)
String
Name of this component, addressable in the parameter list for the calling servlet.
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 servlet query tag 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.

This component responds to the following browser events:

Event
Occurs when
onBlur
Input focus is removed from the element
onChange
Selected value is changed
onFocus
Input focus is given to the element

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

Note that the Tile 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.

For more information on tiles, see Using the Tile Attribute in a GX Markup Tag

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

Property
Values
Description
ResultSet (ID)
Row set
Name of the servlet ResultSet used to populate this component.
GX Tag Type
TILE
Type of GX tag. This property is not editable.
Max Rows
Integer
Maximum number of rows to display at runtime.
Min Rows
Integer
Minimum number of rows to display at runtime.
Visible
True or false
Determines whether the portion of the page enclosed by this component appears in the final HTML page when an servlet merges data with the JSP. Set to false to hide a marked-off portion of the page.

 

© Copyright 1999 Netscape Communications Corp.