[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:

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:

<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