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.
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:
<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_DESCRIPTOR ...>
<JSB_ICON...>
<JSB_PROPERTY ...>
...
<JSB_EVENT ...>
...
<JSB_METHOD ...>
...
<JSB_PARAMETER>
...
</JSB_METHOD>
...
<JSB_CONSTRUCTOR ...> </JSB_CONSTRUCTOR>
</JSB>
<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. §
<JSB_DESCRIPTOR>
component descriptor tag that provides a component's actual name, environment type, display name, and hint text.
<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.
<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.
<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.
<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.
<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.
<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.
<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
.
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> </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.
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 JavaFeatureDescriptor
base class. §
<JSB_DESCRIPTOR>
tag.
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
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>
Table 8.2 Possible values for the <JSB_DESCRIPTOR> ENV attribute
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.
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">
See also: <JSB_CONSTRUCTOR> </JSB_CONSTRUCTOR>,
</JSB_CONSTRUCTOR><JSB_PROPERTY>
ENV attribute, <JSB_METHOD>
ENV attribute
Table 8.3 Possible values for the <JSB_PROPERTY> EVENTMODEL 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:
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 ofHELP_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.
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
takes the following form:
NEEDSFORM
SHORTDESCRIPTION
takes the following form:
SHORTDESCRIPTION="tiptext"This attribute is a string.
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>
differs from the JavaBeans specification in that only one icon file can be specified per component.
<JSB_ICON>
tag.
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>
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 JavaFeatureDescriptor
base class. §
<JSB_PROPERTY>
tag.
DEFAULTVALUE
takes the following form:
DEFAULTVALUE="value"where value is a property value.
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
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
takes the following form:
DISPLAYNAME="propname"
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
See also: <JSB_DESCRIPTOR>, ENV attribute for <JSB_DESCRIPTOR>
Table 8.5 Possible values for the <JSB_PROPERTY> EVENTMODEL attribute
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:
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
Table 8.6 Possible values for the <JSB_PROPERTY> PROPTYPE attribute
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
.
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="accesstype"where
accesstype
is one of the values listed in the following table:.Table 8.7 Possible values for the <JSB_PROPERTY> RUNTIMEACCESS attribute
Table 8.8 Possible values for the <JSB_PROPERTY> TYPE attribute
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:
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
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>
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 JavaFeatureDescriptor
base class. §
<JSB_METHOD>
tag.
DISPLAYNAME
takes the following form:
DISPLAYNAME="methodname"
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
See also: <JSB_DESCRIPTOR>, ENV attribute for <JSB_DESCRIPTOR>
Table 8.10 Possible values for the <JSB_METHOD> TYPE attribute
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:
<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 JavaFeatureDescriptor
base class. §
<JSB_EVENT>
tag.
<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>,
Table 8.11 Possible values for the <JSB_EVENT> EVENTMODEL attribute
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:
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 forSee also: <JSB_METHOD> </JSB_METHOD><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 JavaFeatureDescriptor
base class. §
Table 8.12 Possible values for the <JSB_PARAMETER> TYPE attribute
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:
<JSB_CONSTRUCTOR>
Encapsulates the JavaScript script that constructs the component. The constructor can contain an embedded script, or can include a
</JSB_CONSTRUCTOR>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>
The script may also define helper functions for the component.
function netscape_sample_SampleScrollingBanner (params) {
. . .
}
</JSB_CONSTRUCTOR> 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 JavaFeatureDescriptor
base class. §
<JSB_INTERFACE>
.
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.
Last Updated: 11/20/97 13:56:40