[Previous] [Contents]

## Chapter 8
JSB File Structure Reference

## JSB File Structure Reference

This document describes the structure of the JavaScript Bean (JSB) file and provides a reference to JSB file tag and attribute syntax.

A JSB file is used to communicate metainformation about a Netscape ONE component to any platform or tool, such as Visual JavaScript (VJS), that recognizes the JSB file format. Component metainformation is used to make connections between components, and to manipulate and inspect components at design time, such as through the VJS Inspector.

A JSB file may also provide additional component information, depending on the type of component it describes. For example, JavaScript components exist only as JSB files. A JSB file for a JavaScript component includes a constructor script, and may include JavaScript functions that support the constructor script, or that process events.

The JSB file structure is modeled on the JavaBeans `BeanInfo` class with extensions that support specific features of the Netscape ONE platform and development tools, such as VJS. The following sections describe the JSB file structure and provide a reference for JSB syntactic elements.

## Uses of the JSB File

The following table lists the intended uses for JSB files in VJS:

Table 8.1 JSB file uses

Use | Description
--- | ---
Definition of JavaScript Components | Defines components that are constructed completely from JavaScript. This is the most common use of the JSB file.
Definition of HTML elements | Defines files loaded explicitly from VJS in order to retrieve information about the properties and events of an object that are generated at run time from an HTML tag. For example, form elements fall into this category. JSB files that contain HTML element definitions are given a default extension of HI to distinguish them from JSB files that contain components for import or export.
Implementation of hidden Java classes | Defines metainformation for a Java class, while hiding the actual class implementation. For example, this is the only way to work with server-side Java components in VJS, and is typically used with LiveConnect to instantiate a Java class from JavaScript. The intention here is that only part of the underlying class need be exposed through the JSB file as long as the class can be instantiated using the JavaScript new operation.
Definition of CORBA components | Defines a CORBA component for VJS and the Netscape ONE platform in terms of the IDL definition of the original CORBA object. VJS automatically creates the JSB file for a CORBA object when you import the object.

## Overview of the JSB File Structure

A JSB file consists of text tags that encapsulate a single component definition. The file format is plain text that can be parsed according to SGML rules. Tags are enclosed in angle brackets, and can be nested as appropriate. A component definition in a JSB file is enclosed by a `<JSB>` and `</JSB>` tag pair. This pair contains embedded tags that define metainformation for the component. For example, all components defined in a JSB file contain tags that define some or all of the following information:

- Properties of the object. Depending on the component, some properties can be queried and set directly. Others require Get and Set methods. Properties are defined in a JSB file using property descriptors.

- Methods for the object, and parameters for each method. Methods are defined in a JSB file using method descriptors.

- Events to which scripts can be assigned, and which are evaluated by JavaScript when the trigger condition occurs. Events are defined in a JSB file using event set descriptors. CORBA components do no have events.

- Interfaces that enable Java classes to handle component events. There is typically one interface for each event. CORBA components do not have interfaces.

- A constructor that initializes the component and contains the actual code for the component's methods and events. Only JSB files for JavaScript components contain constructors.

Typically, a skeleton JSB file looks like this:

    <JSB>
       <JSB_DESCRIPTOR ...>
       <JSB_ICON...>
       <JSB_PROPERTY ...>
       ...
       <JSB_EVENT ...>
       ...
       <JSB_METHOD ...>
       ...
          <JSB_PARAMETER>
          ...
       </JSB_METHOD>
       ...
       <JSB_CONSTRUCTOR ...> </JSB_CONSTRUCTOR>
    </JSB>

Depending on a component's event definitions, the JSB file may also contain interface definitions that enable handling a component's events through an external object, such as another Java component. Each interface is defined in a `<JSB_INTERFACE>` tag.

JavaScript components defined in separate JSB files can share interfaces. To share an interface, provide the identical interface definition for each component in that component's JSB file. §

### Component Descriptor

The first tag embedded in a component definition is the `<JSB_DESCRIPTOR>` component descriptor tag that provides a component's actual name, environment type, display name, and hint text.

### Icon Descriptor

A component definition can include an optional `<JSB_ICON>` tag that defines icon information for the component, including the name of the file that contains the 16x16 pixel color GIF for the component.

### Property Descriptors

Each component property must have a `<JSB_PROPERTY>` property descriptor tag in the JSB file. A property descriptor defines a property's unique name and type. It can optionally specify a property editor class, and the Get and Set methods that enable an application to retrieve and set the property's value.

If the Get and Set methods are specified for a property, the JSB file must also contain the corresponding method descriptors for those methods. If the Get and Set methods are not specified, or if they are null, VJS automatically creates them at design time. The Get method uses an expression of the type `object.property` to retrieve a value. The Set method is created using an assignment expression to set the property.

At design time, a property is assigned an initial value that must be translated into a proper literal form for embedding in an HTML page. Properties are stored into the page in different ways, depending on the type of property.

Finally, a property can be bound, meaning that an event is triggered when the property value changes. A property must be bound in order for VJS to establish a property connection from this component to another one.

### Method Descriptors

Methods are functions that operate on a component, its properties, and its data. Each method defined for a component must be encapsulated in a `<JSB_METHOD>` and
`</JSB_METHOD>` method descriptor tag pair in the JSB file. A method descriptor defines a method's name, its return type, and its parameters, if any.

Each parameter must be placed in a parameter descriptor that is embedded in the method descriptor.The parameter descriptor specifies the parameter's name and type.

Method descriptors must be created for each Get and Set method defined for a property. Method descriptors must also be created for methods that provide support functions for a component's event handlers.

### Event Set Descriptors

Events are methods that are triggered when a certain condition occurs within a component (for instance, when the value of a property changes). Events are typically callbacks to methods belonging to other objects outside the component. The `<JSB_EVENT>` event set descriptor tag specifies the name of the event, the event model to which the event conforms, and, depending on the specified event model, a listener type parameter that specifies the name of the interface used by the component.

The event model determines whether or not a listener type parameter must be defined for the component. If the event model corresponds to the AWT11 interface, the listener type parameter is required.

### Constructor

The `<JSB_CONSTRUCTOR>` and `</JSB_CONSTRUCTOR>` tag pair enclose the JavaScript code that creates instances of the component at run time, defines a component's methods, and links the actual implementation of those methods to the component's method descriptors. All JavaScript components must have a constructor definition, or must point to an external JS file on a server that provides the definition.

### Interfaces

The `<JSB_INTERFACE>` tag describes the interface information a component returns to a Java object that implements the actual interface. The interface enables VJS to determine which external Java objects can handle a component's events when they are triggered. Using an external object to handle events enables sharing of event handlers across JavaScript components.

### Attributes

Most JSB tags, including `<JSB_DESCRIPTOR>`, `<JSB_ICON>`, `<JSB_PROPERTY>`, `<JSB_METHOD>`, `<JSB_CONSTRUCTOR>`, and `<JSB_INTERFACE>`, have attributes that provide unique tag information. For example, all tags have a `NAME` attribute that provides a unique identifier for the tag.

The names you assign to attributes must be unique throughout a JSB file. Furthermore, the names should not duplicate JavaScript or JSB reserved words. Reserved words are those keywords that provide JS or JSB syntax, such as `SRC` or `SCRIPT`.

## Creating a JSB File

Because a JSB file is in plain text format, you can create it with any editor capable of producing unformatted text.

> NOTE: On Windows platforms, the CDK ships with the Acadia JSBean Builder, which you can also use to create JS components. The Acadia JSBean Builder is not described in this document, but it and its supporting documentation is delivered as part of the CDK. §

## JSB Tag Reference

The following sections describe tags and tag attributes used in JSB files. The heading for each tag type indicates whether or not a tag requires a matching end tag. For example, a heading such as `<JSB> </JSB>` indicates tags that are part of a pair. A heading such as `<JSB_PROPERTY>` indicates a tag that does not require an end tag.

The text that follows a heading describes the main purpose of the tag. Next is a list of tag attributes, if any. The description of the attribute states it purpose, indicates if the attribute is required or optional, and specifies possible attribute values when there is a restricted list of values.

### <JSB> </JSB>

Encapsulates a component's definition, including its properties, events, methods, and constructor tags.

#### Attributes

None.

### <JSB_DESCRIPTOR>

Provides general component information, such as the component's name, display name, and environment where the component executes at run time.

> NOTE: In addition to the attributes already defined for `<JSB_DESCRIPTOR>`, you can provide custom attributes that follow standard SGML formatting conventions. Extensions are roughly mapped into the corresponding attributes supported by name in the Java `FeatureDescriptor` base class. §

#### Attributes

The following attributes are used with the `<JSB_DESCRIPTOR>` tag.

##### CUSTOMIZER

Specifies a Java class used to customize the component. Optional. If used, `CUSTOMIZER` takes the following form:

    CUSTOMIZER="packagename.packageclass"

where packagename is the name of the Java package to use, and packageclass is the name of the class to use for customizing the JavaScript component. In VJS, the customizer must be derived from or extend `NSCustomizer`.

##### DISPLAYNAME

Specifies a name for the component that can be used for display purposes. Required. VJS displays this name in the object inspector. `DISPLAYNAME` takes the following form:

    DISPLAYNAME="componentclassname"

The component name is a string. Usually it reflects the class name or constructor name of the object that implements the component.

See also: <JSB_CONSTRUCTOR> </JSB_CONSTRUCTOR>

##### ENV

Specifies the environment where the component runs. Optional. `ENV` takes the following form:

    ENV="value"

where value can be one of the values in the following table. The table summarizes possible values for `ENV`, and what those values signify.

Table 8.2 Possible values for the <JSB_DESCRIPTOR> ENV attribute

Value | Meaning
--- | ---
"client" | Component runs on the client. When the JSB file is processed, its code is automatically placed within `<SCRIPT>` tags in the HTML document.
"server" | Component runs on the server. When the JSB file is processed, its code is automatically placed within `<SERVER>` tags in the HTML document.
"both" | An instance of the component is generated at run time on both the client and the server. If this setting is specified, then each property and method defined for the component must specify individual `ENV` attributes to specify where they are instantiated at run time.
"either" | Component can run either on the server or the client, as determined by the application developer. This is the default behavior if `ENV` is not specified.

If `ENV` is not specified, the value "`either`" is assumed. You decide whether a component executes on the server or the client.

For any component that can run on the server, you must create a separate JS file on the server that defines the component's constructor function, and point to that file in the `SRC` attribute of the `<JSB_CONSTRUCTOR>` tag. For example:

    <JSB_CONSTRUCTOR SRC="SampleScrollingBanner.js">
    </JSB_CONSTRUCTOR>

See also: <JSB_CONSTRUCTOR> </JSB_CONSTRUCTOR>, `<JSB_PROPERTY>` ENV attribute, `<JSB_METHOD>` ENV attribute

##### EVENTMODEL

Specifies which event model is used by this component. Optional. VJS uses the `EVENTMODEL` attribute to determine how to connect components. `EVENTMODEL` takes the following form:

    EVENTMODEL="model"

where model is one of:

Table 8.3 Possible values for the <JSB_PROPERTY> EVENTMODEL attribute

Value | Meaning
--- | ---
`JS` | A method body is created by VJS and assigned to the Java Script object.
`AWT11` | Add and remove listener methods are used at run time to connect components.
`HTML` | Permits connection to HTML built-in objects (e.g., form elements). This is not an actual event model, but it enables VJS to construct function bodies for `onChange` or `onClick` events.

If `EVENTMODEL` is omitted in `<JSB_DESCRIPTOR>`, you must supply a separate `EVENTMODEL` attribute for each event and property that uses an event.

See also: EVENTMODEL for <JSB_PROPERTY>, EVENTMODEL for <JSB_EVENT>

##### HELP_URL

Specifies a string containing a valid URL for a page containing help on a component. Optional. Application developers can view the help page in Communicator or Navigator when they choose More Info from the VJS menu. `HELP_URL` takes one of the following forms:

    HELP_URL="uniformresourcelocator"

    HELP_URL="$INSTALLDIRuniformresourcelocator"

where uniformresourcelocator is a valid URL for the help page, and `$INSTALLDIR` is a string literal, that, if present, forces VJS to load the help page from a directory relative to the VJS installation directory.

An URL that is not relative to the VJS install directory can start with`http://` or `file:///`. Use `http://` when a user is connected to the Internet and the help file resides remotely on an Internet server. Use `file:///` for a local help file that resides on the user's machine.

> NOTE: Use the `$INSTALLDIR` form of `HELP_URL` whenever possible. It provides a platform- independent method of assuring that a help file moves with a component archive and with a given VJS palette. If a help file is copied to the project, it travels with the project, and can be reimported to the palette.

##### ISHIDDEN

Specifies to a component development tool, such as VJS, that a component should not be visible in a WYSIWYG view of the application page where the component resides. Optional. If omitted, the component is displayed. If present, the component is not displayed in a WYSIWYG view.

##### NAME

Specifies the unique identifier for the component. Required. `NAME` takes the following form:

    NAME="packagename.componentname"

where packagename is the name of the package containing the component, and componentname is the unique name of a component in the specified package.

##### NEEDSFORM

Indicates that a component must be placed in a form on an HTML page, and instructs VJS to create a form for the component if necessary. Optional. `NEEDSFORM` takes the following form:

    NEEDSFORM

##### SHORTDESCRIPTION

Provides a brief description of the component class that is displayed in VJS Tool Tips. Optional. `SHORTDESCRIPTION` takes the following form:

    SHORTDESCRIPTION="tiptext"

This attribute is a string.

##### VISUAL

Specifies the name of a class used to provide the design time visual appearance of a component. Optional. `VISUAL` takes the following form:

    VISUAL="packagename.packageclass"

where packagename is the name of the Java package to use, and packageclass is the name of the class to use for providing the component's design time appearance. Instances of this class are passed to the engine for Layout view.

In VJS, packageclass must be one of `HTMLFlowable`, `HTMLContextMenu`, `ActionListener`, or `RemovablePropertyChangeListener`.

### <JSB_ICON>

Provides the name of the file containing a display icon for a component. `<JSB_ICON>` differs from the JavaBeans specification in that only one icon file can be specified per component.

#### Attributes

The following attributes are used with the `<JSB_ICON>` tag.

##### ICONNAME

Specifies the base file that contains a display icon for the component. Optional. `ICONNAME` takes the following form:

    ICONNAME= "filename"

where file name is a standard file name that can include an optional extension. For example:

    ICONNAME= "myicon.gif"

The file name you specify is both the actual file name of a 16x16 pixel color icon, and a base file name that VJS uses to locate a corresponding 32x32 pixel color icon. VJS appends "32" to the base file name prior to the file extension, if any, and looks for the 32x32 icon file. For example if `ICONNAME` is `myicon.gif`, VJS looks for these files:

- `myicon.gif`, containing the 16x16 pixel color icon

- `myicon32.gif`, containing the 32x32 pixel color icon

### <JSB_PROPERTY>

Defines a property for a component. `<JSB_PROPERTY>` is primarily modeled on the JavaBeans `PropertyDescriptor` object. JavaScript properties, however, can be retrieved and set directly, or through Get and Set methods defined for the component.

> NOTE: In addition to the attributes defined for `<JSB_PROPERTY>`, developers can provide custom attributes that follow standard SGML formatting conventions. Extensions are roughly mapped into the corresponding attributes supported by name in the Java `FeatureDescriptor` base class. §

#### Attributes

The following attributes are used with the `<JSB_PROPERTY>` tag.

##### DEFAULTVALUE

Provides a default value for a property if no other value is assigned. Optional. `DEFAULTVALUE` takes the following form:

    DEFAULTVALUE="value"

where value is a property value.

##### DEFAULT_VALUE

Deprecated alternative for `DEFAULTVALUE`. Provides a default value for a property if no other value is assigned. Optional. `DEFAULT_VALUE` takes the following form:

    DEFAULT_VALUE="value"

where value is a property value.

##### DESIGNTIMEREADONLY

Indicates that at design time the value of this property can be examined, but cannot be set. Optional. If `DESIGNTIMEREADONLY` is specified for a property, the property is grayed out in the Inspector at design time and cannot be set.

`DESIGNTIMEREADONLY` is useful for properties for which initial values are meaningless. For example, a property that reports the current number of rows in a database table is meaningless until run time, when the application accesses the database.

##### DISPLAYNAME

Specifies a name for the property that can be used for display purposes. Required. VJS displays this name in the object inspector. `DISPLAYNAME` takes the following form:

    DISPLAYNAME="propname"

##### ENV

Specifies the environment where the application can retrieve or set a property's value. Optional and meaningful only if the corresponding `ENV` attribute in the `<JSB_DESCRIPTOR>` is set to `"both`". Otherwise `ENV` is ignored if specified for a property. `ENV` takes the following form:

    ENV="value"

where value can be one of the values in the following table.

Table 8.4 Possible values for the <JSB_PROPERTY> ENV attribute

Value | Meaning
--- | ---
"client" | Property is retrieved and set on the client.
"server" | Property is retrieved and set on the server.
"both" | Property is retrieved and set on the client and the server. This is the default if `ENV` is not specified for the property.

See also: <JSB_DESCRIPTOR>, ENV attribute for `<JSB_DESCRIPTOR>`

##### EVENTMODEL

Specifies which event model is used by this property. Required if a global `EVENTMODEL` is not specified in the `<JSB_DESCRIPTOR>` tag, or if the event model used by this property overrides the globally assigned event model. VJS uses the `EVENTMODEL` attribute to determine how to connect components. `EVENTMODEL` takes the following form:

    EVENTMODEL="model"

where model is one of:

Table 8.5 Possible values for the <JSB_PROPERTY> EVENTMODEL attribute

Value | Meaning
--- | ---
`JS` | A method body is created by VJS and assigned to the Java Script object.
`AWT11` | Add and remove listener methods are used at run time to connect components.
`HTML` | Permits connection to HTML built-in objects (e.g., form elements). This is not an actual event model, but it enables VJS to construct function bodies for `onChange` or `onClick` events.

##### ISBOUND

Specifies that an `onChange` event is triggered when a property's value is changed. Optional.

The type of event that is triggered depends on the property's `PROPTYPE` attribute.

See also: PROPTYPE

##### ISDEFAULT

Indicates that this property is the default property of the component. Optional. If `ISDEFAULT` is omitted for all component properties, the first property listed in the JSB file automatically becomes the default property. If more than one property is assigned the `ISDEFAULT` attribute, the first property with this attribute becomes the default, and all other `ISDEFAULT` attributes for properties are ignored.

##### ISEXPERT

Indicates that this property is an expert property that is not displayed in the VJS Inspector. Optional. Expert properties usually define some predefined or fixed value that component users should not need to examine or manipulate at design time. At run time, other internal methods of a component may read or write an expert property, but usually an application developer will not produce additional code that directly reads or writes an expert property. An application can call the `isExpert` method on a property to determine if the `ISEXPERT` attribute is declared for the property. Exercise care if you decide to access or change the value of an expert property.

##### NAME

Specifies a unique identifier for a property. Required. `NAME` is used in direct reference expressions to retrieve or set a property's value when Get and Set methods are not provided for the property. `NAME` takes the following form:

    NAME="propname"

where propname is a unique property name within this component.

##### PROPERTYEDITOR

Specifies a Java class the VJS inspector uses to edit the property's value. Optional. `PROPERTYEDITOR` takes the following form:

    PROPERTYEDITOR="packagename.classname"

where packagename is the fully qualified package name containing the Java class, and classname is the name of the Java class to use as the property editor.

##### PROPTYPE

Determines how a property is stored in the HTML document, and how the property is treated if it is a bound property. The following table lists the possible values for `PROPTYPE`.

Table 8.6 Possible values for the <JSB_PROPERTY> PROPTYPE attribute

Value | Meaning
--- | ---
JS | Stores a property using JavaScript inside a `<SCRIPT>` tag to form a parameter object that is passed to the constructor.
TagAttribute | Stores a property in the HTML document as an attribute of the property tag. This option is primarily intended to support `.HI` files that describe HTML form elements and other built-in browser objects.
AWT11 | Indicates that a property is accessed exclusively through Get and Set methods, like a JavaBeans component.

##### READMETHOD

Specifies the name of the Get method used to retrieve the value of the property at run time. Optional. `READMETHOD` takes the following form:

    READMETHOD="methodname"

where methodname corresponds to the name of a `<JSB_METHOD>` tag defined elsewhere in the JSB file.

> NOTE: The return value of the specified Get method must correspond to the property's `TYPE` attribute. §

If `READMETHOD` is not specified for the property, an application can query directly for a property's value using standard JavaScript `variable=object.property` syntax. If the component is a LiveConnect component (that is, a Java component), the standard JavaBeans naming conventions are used to attempt to locate the Get method for the property.

##### RUNTIMEACCESS

Specifies the run time access for a property. Optional. RUNTIMEACCESS corresponds to a member of PropertyProfile. The value assigned to RUNTIMEACCESS is used by the VJS Connection Builder to determine which target properties can provide property connections. RUNTIMEACCESS takes the following form:

    RUNTIMEACCESS="accesstype"

where `accesstype` is one of the values listed in the following table:.

Table 8.7 Possible values for the <JSB_PROPERTY> RUNTIMEACCESS attribute

Value | Meaning
--- | ---
FULL | Property is read and write accessible. This is the default for a property if `RUNTIMEACCESS` is not specified.
READONLY | Property is read only at run time, and is not available for property connections in the VJS Connection Builder.
NONE | Property is not accessible at run time, and is not available for property connections in the VJS Connection Builder.

##### SHORTDESCRIPTION

Provides a brief description of the property that is displayed in VJS Tool Tips. Optional. `SHORTDESCRIPTION` takes the following form:

    SHORTDESCRIPTION="tiptext"

##### TYPE

Indicates the data type for the property. Required. `TYPE` is either a JavaScript data type, a primitive Java data type, or the fully qualified package name of a Java class that describes a data type. `TYPE` takes one of the following forms, depending on whether the specified data type is a JavaScript data type, Java primitive, or a Java class:

Table 8.8 Possible values for the <JSB_PROPERTY> TYPE attribute

Type Origin | Syntax
--- | ---
Java primitive data class |
    TYPE="datatype"
where datatype is a Java primitive data type, such as int or bool.
Java class |
    TYPE="package.class"
where package is the Java package containing a data type class, and class is the Java class that defines the data type.
JavaScript data type |
    TYPE="JSdatatype"
where JSdatatype is one of string, number, boolean, or void.

##### WRITEMETHOD

Specifies the name of the Set method used to set the value of the property at run time. Optional. `WRITEMETHOD` takes the following form:

    WRITEMETHOD="methodname"

where methodname corresponds to the name of a `<JSB_METHOD>` tag defined elsewhere in the JSB file.

> NOTE: The Set method must have a single parameter that corresponds to the property's data type. §

If `WRITEMETHOD` is not specified for the property, an application can directly set a property's value using standard JavaScript `object.property= value` syntax. If the component is a LiveConnect component (that is, a Java component), the standard JavaBeans naming conventions are used to attempt to locate the Set method for the property.

##### VALUESET

Specifies a range of allowed values for the property. Optional. Use `VALUESET` to limit possible property values. `VALUESET` takes the following form:

    VALUESET="range"

where range is a string containing a list of possible values. The interpretation of the string depends upon the data type of the property. For string properties, the `VALUESET` should be a comma-delimited list of strings. For example:

    VALUESET="ORACLE,INFORMIX,SYBASE,ODBC"

For numeric properties, `VALUESET` can be a comma delimited list of values or ranges, where a range follows a `min:max` pattern. For example:

    VALUESET="1:32,64"

which indicates that a property can have values from 1 to 32 and 64.

> NOTE: Because `VALUESET` is a string, the property editor must be able to parse values in the string. §

### <JSB_METHOD> </JSB_METHOD>

Defines a method for a component. `<JSB_METHOD>` is primarily modeled on the JavaBeans `MethodDescriptor` and `Method` objects.

> NOTE: In addition to the attributes already defined for `<JSB_METHOD>`, you can provide custom attributes that follow standard SGML formatting conventions. Extensions are roughly mapped into the corresponding attributes supported by name in the Java `FeatureDescriptor` base class. §

#### Attributes

The following attributes are used with the `<JSB_METHOD>` tag.

##### DISPLAYNAME

Specifies a name for the method that can be used for display purposes. Required. VJS displays this name in the VJS Inspector. `DISPLAYNAME` takes the following form:

    DISPLAYNAME="methodname"

##### ENV

Specifies the environment where the method resides. Optional and meaningful only if the corresponding `ENV` attribute in the `<JSB_DESCRIPTOR>` is set to `"both"`. Otherwise `ENV` is ignored if specified for a method. `ENV` takes the following form:

    ENV="value"

where value can be one of the values in the following table.

Table 8.9 Possible values for the <JSB_METHOD> ENV attribute

Value | Meaning
--- | ---
"client" | Method can be called by components on the client.
"server" | Method can be called by components on the server.
"both" | Method can be called by components on the client or server. This is the default if `ENV` is not specified for the method.

See also: <JSB_DESCRIPTOR>, ENV attribute for `<JSB_DESCRIPTOR>`

##### ISEXPERT

Indicates that this method is an expert method that is not displayed in the VJS Inspector. Optional. Expert methods are typically internal support methods called by other methods belonging to the component. Ordinarily your component users should not need to call expert methods. If you expect or require users to access a method, do not designate it as an expert method.

##### NAME

Specifies a unique identifier for a method. Required. `NAME` is used in scripts to call the method. `NAME` takes the following form:

    NAME="methodname"

where methodname is a unique method name within this component.

##### SHORTDESCRIPTION

Provides a brief description of the method that is displayed in VJS Tool Tips. Optional. `SHORTDESCRIPTION` takes the following form:

    SHORTDESCRIPTION="tiptext"

##### TYPE

Indicates the data type for a method's return type. Required. `TYPE` is can be a JavaScript data type, a primitive Java data type, or the fully qualified package name of a Java class that describes a data type. `TYPE` takes one of the following forms, depending on whether the specified data type is a JavaScript data type, Java primitive, or Java class:

Table 8.10 Possible values for the <JSB_METHOD> TYPE attribute

Type Origin | Syntax
--- | ---
Java primitive data class |
    TYPE="datatype"
where datatype is a Java primitive data type, such as int or bool.
Java class |
    TYPE= "package.class"
where package is the Java package containing a data type class, and class is the Java class that defines the data type.
JavaScript data type |
    TYPE= "JSdatatype"
where JSdatatype is one of string, number, boolean, or void.

### <JSB_EVENT>

Defines an event for a component. `<JSB_EVENT>` is primarily modeled on the JavaBeans `EventSetDescriptor` object.

> NOTE: In addition to the attributes already defined for `<JSB_EVENT>`, you can provide custom attributes that follow standard SGML formatting conventions. Extensions are roughly mapped into the corresponding attributes supported by name in the Java `FeatureDescriptor` base class. §

#### Attributes

The following attributes are used with the `<JSB_EVENT>` tag.

##### ADDLISTENERMETHOD

Specifies the name of the method used to add a listener method for the event. Required for the AWT11 event model if the listener methods belong to another object. The add method named here must be defined for this component using a `<JSB_METHOD>
</JSB_METHOD>` tag pair.

`ADDLISTENERMETHOD` takes the following form:

    ADDLISTENERMETHOD= "addMethod"

where addMethod is the name of the method that adds a listener method for the event.

See also: <JSB_METHOD> </JSB_METHOD>,

##### DISPLAYNAME

Specifies a name for the event that can be used for display purposes. Required. VJS displays this name in the VJS Inspector. `DISPLAYNAME` takes the following form:

    DISPLAYNAME="eventname"

##### EVENTMODEL

Specifies which event model is used by this event. Required if a global `EVENTMODEL` is not specified in the `<JSB_DESCRIPTOR>` tag, or if the event model used by this event overrides the globally assigned event model. VJS uses the `EVENTMODEL` attribute to determine how to connect components. `EVENTMODEL` takes the following form:

    EVENTMODEL="model"

where model is one of:

Table 8.11 Possible values for the <JSB_EVENT> EVENTMODEL attribute

Value | Meaning
--- | ---
`JS` | A method body is created by VJS and assigned to the Java Script object.
`AWT11` | Add and remove listener methods are used at run time to connect components.
`HTML` | Permits connection to HTML built-in objects (e.g., form elements). This is not an actual event model, but it enables VJS to construct function bodies for `onChange` or `onClick` events.

##### ISDEFAULT

Indicates that this event is the default event for the component. Optional. If `ISDEFAULT` is omitted for all component events, the first event listed in the JSB file automatically becomes the default event for the component. If more than one event is assigned the `ISDEFAULT` attribute, the first event with this attribute becomes the default, and all other `ISDEFAULT` attributes for events are ignored.

##### ISEXPERT

Indicates that this event is an expert event that is not displayed in the VJS Inspector. Optional. Expert events are typically internal events called by other methods or events belonging to the component. Ordinarily your component users should not need to trigger an expert event. If you expect or require users to trigger the event, do not designate it as an expert event.

##### LISTENERTYPE

Specifies the name of the Java package and class that implements the listener interface that must be supported by the receiving object. Required for the AWT11 event model.

`LISTENERTYPE` takes the following form:

    LISTENERTYPE= "eventListener"

where eventListener corresponds to the name of a `<JSB_INTERFACE>` tag.

The JSB file must include a `<JSB_INTERFACE>` tag that specifies the interface.

See also: <JSB_INTERFACE>

##### REMOVELISTENERMETHOD

Specifies the name of a method used to remove a listener method for the event. Required for the AWT11 event model if the listener methods belong to another object. The remove method named here must be defined for this component using a `<JSB_METHOD> </JSB_METHOD>` tag pair.

`REMOVELISTENERMETHOD` takes the following form:

    REMOVELISTENERMETHOD= "deleteMethod"

where deleteMethod is the name of the method that deletes a listener method from the event.

See also: <JSB_METHOD> </JSB_METHOD>

##### NAME

Specifies a unique identifier for an event. Required. `NAME` is used in scripts to call the event. `NAME` takes the following form:

    NAME="eventname"

where eventname is a unique event name within this component.

##### SHORTDESCRIPTION

Provides a brief description of the event that is displayed in VJS Tool Tips. Optional. `SHORTDESCRIPTION` takes the following form:

    SHORTDESCRIPTION="tiptext"

### <JSB_PARAMETER>

Defines a parameter for a method belonging to the component. Parameter tags are always embedded within `<JSB_METHOD>` tags in a JSB file. `<JSB_PARAMETER>` is primarily modeled on the JavaBeans `ParameterDescriptor` object.

> NOTE: In addition to the attributes already defined for `<JSB_PARAMETER>`, you can provide custom attributes that follow standard SGML formatting conventions. Extensions are roughly mapped into the corresponding attributes supported by name in the Java `FeatureDescriptor` base class. §

See also: <JSB_METHOD> </JSB_METHOD>

#### Attributes

The following attributes are used with the `<JSB_PARAMETER>` tag.

##### DISPLAYNAME

Specifies a descriptive name for the parameter that can be used for display purposes. Optional. VJS displays this name in the VJS Inspector. `DISPLAYNAME` takes the following form:

    DISPLAYNAME="paramname"

If `DISPLAYNAME` is omitted, VJS substitutes the `NAME` attribute.

##### NAME

Specifies a unique identifier for the parameter. Optional. If provided, `NAME` can be used for display purposes in VJS.

    NAME="paramname"

where paramname is a unique parameter name for the method.

##### SHORTDESCRIPTION

Provides a brief description for the parameter that is displayed in VJS Tool Tips. Optional. `SHORTDESCRIPTION` takes the following form:

    SHORTDESCRIPTION="tiptext"

##### TYPE

Indicates the data type for a parameter's return type. Required. The value of `TYPE` is a JavaScript data type, or the fully qualified package name of a Java class that describes a data type. `TYPE` takes one of the following forms, depending on whether the specified data type is a JavaScript data type or a Java class:

Table 8.12 Possible values for the <JSB_PARAMETER> TYPE attribute

Type Origin | Syntax
--- | ---
Java class |
    TYPE= "package.class"
where package is the Java package containing a data type class, and class is the Java class that defines the data type.
JavaScript data type |
    TYPE= "JSdatatype"
where JSdatatype is one of `string`, `number`, or `boolean`.

### <JSB_CONSTRUCTOR>
</JSB_CONSTRUCTOR>

Encapsulates the JavaScript script that constructs the component. The constructor can contain an embedded script, or can include a `SRC` attribute that indicates the location of the script used to build the component. A script must, at a minimum, define a function that matches the `NAME` attribute of the `<JSB_DESCRIPTOR>` tag, except that embedded dots in `NAME` must be replaced by underscores in the function definition. For example, given the following descriptor:

    <JSB_DESCRIPTOR NAME="netscape.sample.SampleScrollingBanner">

then a minimum constructor would be as follows:

    <JSB_CONSTRUCTOR>
       function netscape_sample_SampleScrollingBanner (params) {
       . . .
       }
    </JSB_CONSTRUCTOR>

The script may also define helper functions for the component.

#### Attributes

The following attribute can be used with the `<JSB_CONSTRUCTOR>` tag.

##### SRC

Specifies the JS file containing the script used to construct a component. Required when for a component that can be created on the server or the client (`JSB_DESCRIPTOR` `ENV="either"`); optional otherwise. `SRC` takes the following form:

    SRC="filename"

where filename is the name of the JS file containing the constructor script for the component.The script in the JS file must compile in the server environment. The JS file must reside in the root of the package hierarchy.

If you specify the `SRC` attribute, then the body of the constructor in the JSB file must be empty. For example:

    <JSB_CONSTRUCTOR SRC="SampleScrollingBanner.js">
    </JSB_CONSTRUCTOR>

### <JSB_INTERFACE>

Specifies an interface that can be returned from the `getInstanceOf` command.Optional. If present, `<JSB_INTERFACE>` is used by VJS to determine which Java objects can handle events associated with the component.

> NOTE: In addition to the attribute already defined for `<JSB_INTERFACE>`, you can provide custom attributes that follow standard SGML formatting conventions. Extensions are roughly mapped into the corresponding attributes supported by name in the Java `FeatureDescriptor` base class. §

#### Attributes

The following attribute must be used with `<JSB_INTERFACE>`.

##### NAME

Indicates the unique identifier for the interface class. Required. `NAME` must be a fully qualified package name. `NAME` takes the following form:

    NAME= "packagename.class"

where packagename is the fully qualified package name containing the interface class, and class is the name of the interface in the package.

[Previous] [Contents]

Last Updated: 11/20/97 13:56:40

Copyright © 1997 Netscape Communications Corporation