Notes on using the API Routines

The aClass Parameter

The majority of the RealWeb API routines include an aClass parameter. This is a DataBasic dynamic array 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 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 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.