Notes on using the API Routines

The aClass Parameter

The majority of the RealWeb API Application Programming Interface - a set of functions that you can use in your programs to work with a component.  routines include an aClass parameter. This is a DataBasic dynamic array A multi-element string variable in which data is divided into elements by attribute marks, value marks and subvalue marks, matching the structure of a Reality file item. The entire array is referenced and stored as a single variable. For more information, refer to the Reality DataBasic Reference Manual.  that can be used to set tag attributes in addition to those specified by the other subroutine parameters (parameters are only provided for the most commonly used attributes).

The elements in the aClass array can be of two types:

• Routine-specific elements whose meaning depends on their position in the array.
• Other elements, supplied as a name:value pair.

For example, in the RW_SELECT_LIST routine, the aClass Parameter can be used to specify the following:

Element No.	Attribute	Description
1	CLASS	The name of a tag class defined in a CSS Cascading Style Sheet - a mechanism by which the presentation of an HTML page can be separated from the content. A style sheet can be used to determine the appearance of one or more HTML pages. stylesheet.
2	STYLE	The style of the list. Enter MULTIPLE to enable multiple selections.
3	SIZE	The number of lines in the visible section of the select list.
4	ONCLICK	The name of the function to be run when the onClick event occurs.

In addition to the above, any other attribute of the HTML SELECT tag can be explicitly specified as a name:value pair, separated by an equals sign (=). Such elements are copied verbatim into the HTML tag.

The following examples show three ways of setting the aClass parameter:

CLASS = ''		* Initialise the class variable
CLASS<1> = ''		* Do not specify a class
CLASS<2> = 'MULTIPLE'	* Enable multiple selections
CLASS<3> = 5		* Display five lines of the list
CLASS<4> = ''		* Do not specify an onClick function
CLASS<5> = 'ID=MyList'	* Give the list the ID 'MyList'

CLASS = @AM:'MULTIPLE':@AM:5:@AM:@AM:'ID=MyList'

CLASS = 'ID=MyList'	* Specify only an ID

The last example demonstrates that an explicitly-specified attribute can appear in any position following the last non-null position-dependent attribute.

The resulting dynamic array A multi-element string variable in which data is divided into elements by attribute marks, value marks and subvalue marks, matching the structure of a Reality file item. The entire array is referenced and stored as a single variable. For more information, refer to the Reality DataBasic Reference Manual. would then be passed to the RW_SELECT_LIST routine.

Parameter Precedence Rules

Parameters passed to a RealWeb API routine are processed in the following order:

• aClass parameter (processed from left to right).
• Other subroutine parameters, in order from left to right.

The effect of this is as follows:

• Initially, the tag's attributes are determined by any CSS stylesheet class specified in the aClass parameter.
• These can overridden by setting routine-specific elements in the aClass parameter.
• Attributes explicitly specified in the aClass parameter can then be used to override attributes specified earlier in the aClass parameter.
• Finally, any other subroutine parameters take effect.

In the most extreme case an HTML tag attribute could be initially set to a value specified in a CSS class, and then be redefined, first to a value given in a routine-specific element in the aClass parameter, then to a value set by an explicitly specified element appended to aClass, and finally to a value specified in one of the subroutine's other parameters.

The Control parameter is used to alter the internal behaviour of the subroutine and there are no other ways of setting values that are set by Control, therefore its position in the parameter list doesn't matter.