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_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: 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.
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.
DISPLAYNAME="componentclassname"
SHORTDESCRIPTION="tiptext"
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.
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.
<JSB_PROPERTY>
Defines a property for a component. <JSB_PROPERTY> is primarily modeled on the Java Beans 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 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.
NAME="propname"where propname is a unique property name within this component.
DISPLAYNAME="propname"
SHORTDESCRIPTION="tiptext"
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.
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.
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.
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.
NOTE: Although the object inspector might display an ISRUNTIME property at design time, it should not permit setting the value.
ENV="value"where value can be one of the values in the following table.
<JSB_METHOD> </JSB_METHOD>
Defines a method for a component. <JSB_METHOD> is primarily modeled on the Java Beans MethodDescriptor and Method objects.
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.
NAME="methodname"where methodname is a unique method name within this component.
DISPLAYNAME="methodname"
SHORTDESCRIPTION="tiptext"
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.
<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.
NAME="eventname"where eventname is a unique event name within this component.
DISPLAYNAME="eventname"
SHORTDESCRIPTION="tiptext"
EVENTMODEL="model"where model is one of:
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 form:
ADDLISTENERMETHOD= "addMethod"
where addMethod is the name of the method that adds a listener method for the event.
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.
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.
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.
<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.
NAME="paramname"where paramname is a unique parameter name for the method.
DISPLAYNAME="paramname"If DISPLAYNAME is omitted, Visual JavaScript substitutes the NAME attribute.
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: 07/08/97 10:46:18