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. Within this pair, are embedded tags that define meta information for the component. For example, all components defined in a JSB file have tags that define:
<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. Interface definitions follow a component's definition. Each interface definition is placed within <JSB_LISTENER> and </JSB_LISTENER> tags:
<JSB_DESCRIPTOR ...>
<JSB_ICON...>
<JSB_PROPERTY ...>
...
<JSB_EVENT ...>
...
<JSB_METHOD ...>
...
<JSB_PARAMETER>
...
</JSB_METHOD>
...
<JSB_CONSTRUCTOR ...> </JSB_CONSTRUCTOR>
</JSB>
...
</JSB>
<JSB_LISTENER ...> </JSB_LISTENER>
...
NOTE: JavaScript components defined in separate JSB files can share listener interfaces. To share an interface, provide the identical listener interface definition for each component in that component's JSB file.
NOTE: On Windows platforms, the CDK ships with the Acadia JavaScript BeanBuilder which you can also use to create JS components. The Acadia JavaScript BeanBuilder is not described in this document, but it and its supporting documentation is delivered as part of the CDK.
NOTE: In addition to the attributes described below that are already defined for <JSB_DESCRIPTOR>, 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.
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.
DISPLAYNAME="componentclassname"
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.
If this attribute is not specified, "either" is assumed. Whether the component executes on the server or the client is left to the application developer to decide.
ISJAVA
No longer used. Some existing JSB examples in the CDK may include this attribute, but it is no longer needed.
NAME
Specifies the unique identifier for the component. Required. NAME takes the 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.
SHORTDESCRIPTION
Provides a brief description of the component class that is displayed in Visual JavaScript Tool Tips. Optional. SHORTDESCRIPTION takes the form:
SHORTDESCRIPTION="tiptext"
VISUAL
Specifies the name of a class used to provide the design time visual appearance of a component. Optional. VISUAL takes the 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.
<JSB_ICON>
Provides the name of the file containing a display icon for a component. JSB_ICON differs from the Java Beans specification in that only one icon file can be specified per a 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 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:
NOTE: In addition to the attributes described below that are already 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.
DEFAULT_VALUE ="value"where value is a property value.
DISPLAYNAME="propname"
ENV="value"where value can be one of the values in the following table.
ISBOUND
Specifies that when a property's value is changed an onChange event is triggered. Optional.
The type of event that is triggered depends on the property's PROPTYPE attribute.
ISDEFAULT
Indicates that this property is the default property for the component. Optional. If ISDEFAULT is omitted for all component properties, the first property listed in the JSB file automatically becomes the default property for the component. 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.
ISRUNTIME
Specifies that a property's value can only be set at run time. Optional.
Properties that specify the ISRUNTIME attribute are not assigned an initial value at design time. For example, if a property represents the current row for a cursor object, or the number of rows returned in a result set, setting a value at design time is meaningless.
NOTE: Although the object inspector might display an ISRUNTIME property at design time, it should not permit setting the value.
NAME="propname"where propname is a unique property name within this component.
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.
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 read 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 (i.e., a Java component), the standard JavaBeans naming conventions are used to attempt to locate the read method for the property.
SHORTDESCRIPTION="tiptext"
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 (i.e., a Java component), the standard JavaBeans naming conventions are used to attempt to locate the write method for the property.
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 VALAUESET 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.
NOTE: In addition to the attributes described below that are already defined for <JSB_METHOD>, 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.
DISPLAYNAME="methodname"
ENV="value"where value can be one of the values in the following table.
NAME
Specifies a unique identifier for a method. Required. NAME is used in scripts to call the method. NAME takes the 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 Visual JavaScript Tool Tips. Optional. SHORTDESCRIPTION takes the form:
SHORTDESCRIPTION="tiptext"
TYPE
Indicates the data type for a method's return type. 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:
<JSB_EVENT>
Defines an event for a component. <JSB_EVENT> is primarily modeled on the Java Beans EventSetDescriptor object.
NOTE: In addition to the attributes described below that are already defined for <JSB_EVENT>, 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.
ADDLISTENERMETHOD= "addMethod"where addMethod is the name of the method that adds a listener method for the event.
DISPLAYNAME="eventname"
EVENTMODEL="model"where model is one of:
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.
LISTENERMETHODS
Provides a comma-delimited list of methods to call when the event is triggered. Required. Each method listed in this attribute must be defined inside its own <JSB_METHOD>
</JSB_METHOD> tag pair nested within a <JSB_LISTENER> </JSB_LISTENER> tag pair.
LISTENERMETHODS takes the form:
LISTENERMETHODS= "onEvent" [, "onEvent" ...]
where each onEvent name corresponds to a different method to call for the event. At least one such event must be listed.
LISTENERTYPE
Specifies the name of the listener interface that must be supported by the receiving object. Required for the AWT11 event model.
LISTENERTYPE takes the form:
LISTENERTYPE= "eventListener"
where eventListener corresponds to the name of a <JSB_LISTENER> tag defined at the end of the JSB file.
The JSB file must include a <JSB_LISTENER> </JSB_LISTENER> tag pair that specifies the listener interface, particularly the methods that are called by the interface. Note that the <JSB_LISTENER> </JSB_LISTENER> tag pair lies outside the <JSB> </JSB> tag pair that defines the component body.
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 form:
REMOVELISTENERMETHOD= "deleteMethod"
where deleteMethod is the name of the method that deletes a listener method from the event.
NAME
Specifies a unique identifier for an event. Required. NAME is used in scripts to call the event. NAME takes the 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 Visual JavaScript Tool Tips. Optional. SHORTDESCRIPTION takes the 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 Java Beans ParameterDescriptor object.
NOTE: In addition to the attributes described below that are already defined for <JSB_PARAMETER>, 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.
DISPLAYNAME="paramname"If DISPLAYNAME is omitted, Visual JavaScript substitutes the NAME attribute.
NAME="paramname"where paramname is a unique parameter name for the method.
SHORTDESCRIPTION="tiptext"
<JSB_CONSTRUCTOR>
Encapsulates the JavaScript script that constructs the component. The 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_CONSTRUCTOR><JSB_DESCRIPTOR NAME="netscape.sample.SampleScrollingBanner">
then a minimum constructor would be as follows:
<JSB_CONSTRUCTOR>
The script may also define helper functions for the component.
function netscape_sample_SampleScrollingBanner (params) {
. . .
}
</JSB_CONSTRUCTOR> <JSB_INTERFACE>
Specifies an interface that can be returned from the getInstanceOf() command.Optional. If present, <JSB_INTERFACE> is used by Visual JavaScript to determine which Java objects can handle events associated with the component.
NOTE: In addition to the attribute described below that is already defined for <JSB_INTERFACE>, 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.
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.
NOTE: In addition to the attribute described below that is already defined for <JSB_LISTENER>, 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.
NAME= "packagename.class"where packagename is the fully qualified package name containing the listener interface, and class is the name of the interface in the package.
Last Updated: 09/03/97 11:33:54