Functions

Method Summary
Method Attributes	Method Name and Description
	af_activate(controlName) Activates the specified control, i.e.
	af_activateSubform(subformID) Activates the specified subform.
	af_addSubtableRow(subtableViewName) Adds a new row at the end of the specified subtable view.
	af_formAbort() Aborts the form (i.e.
	af_formatDate(date, datePattern, timePattern) Formats a `Date` according to the specified date format, which may represent a date and/or time.
	af_formatNumber(number, pattern) Formats a number according to the specified pattern.
	af_formClose() Closes the form (i.e.
	af_formSend() Submits the form unless form validation or custom onSubmit scripts prevent it.
	af_formSuspend() Suspends the form (i.e.
	af_getMessage(key, args) Returns the localised message with the given key.
	af_getSelectedIndex(comboBoxName) Returns the currently selected (0-based) index of the specified combo box.
	af_getSubtableViewRowCount(subtableViewName) Returns the current number of rows of the specified subtable view.
	af_getValue(controlName, raw) Returns the parsed (or optionally raw, i.e.
	af_hasValue(controlName, raw) Returns whether the control contains a value.
	af_isChecked(controlName, radioValue) Returns whether the specified control (either radio button or check box) is currently checked.
	af_isMarkedInvalid(controlName) Returns whether the control with the specified name is currently marked as invalid.
	af_isOptional(controlName) Returns whether the input control with the specified name is optional, i.e.
	af_makeFormReadOnly() Makes the complete form read only, disables sub-table buttons.
	af_markInvalid(controlName, invalid) Marks the control with the specified name as being invalid (if second parameter is `true` or a string).
	af_parseDate(string, datePattern, timePattern) Parses a date string according to the specified date format, which may represent a date and/or time.
	af_parseNumber(string, pattern) Parses a number string according to the specified number format.
	af_removeSubform(subformID) Completely removes the specified subform and all its controls.
	af_removeSubtableRow(subtableViewName, row) Removes the row at the given index in the specified subtable view.
	af_setBackground(controlName, colour) Sets the background colour of the specified control.
	af_setDisabled(controlName, disabled) Disabled or enables a control.
	af_setGroupBoxCollapsed(groupBoxID, collapsed) Collapses or expands the specified GroupBox.
	af_setGroupBoxDisabled(groupBoxID, disabled) Sets the disabled-state of all controls within the specified group box.
	af_setGroupBoxHidden(groupBoxID, hidden) Collapses & hides or expands & unhides the specified GroupBox.
	af_setGroupBoxReadOnly(groupBoxID, readOnly) Sets the readOnly-state of all controls within the specified group box.
	af_setGroupBoxTitle(groupBoxID, title) Sets the title of the specified GroupBox to the given title.
	af_setHidden(controlName, hidden) Hides or unhides a control.
	af_setHiddenAndDisabled(controlName, hiddenAndDisabled) Combines #af_setHidden and #af_setDisabled.
	af_setReadOnly(controlName, readOnly) Sets the readOnly-state of the specified control.
	af_setRowBackground(subtableViewName, rowIndex, colour) Sets the background colour of the specified subtable view row.
	af_setSelectedIndex(comboBoxName, index, triggerOnChange) Sets the currently selected (0-based) index of the specified combo box.
	af_setSubformDisabled(subformID, disabled) Sets the disabled property for all controls of the specified subform.
	af_setSubformHidden(subformID, hidden) Hides or shows the specified subform.
	af_setSubformReadOnly(subformID, readOnly) Sets the read-only property for all controls of the specified subform.
	af_setValue(controlName, value, triggerEventHandlers) Sets a new value for the control with the given name.

Method Detail

af_activate(controlName)

Activates the specified control, i.e. jumps to the containing subform and assigns the focus to the control. In case of a text box its text will be selected.

Parameters:
{String} controlName: name of the control

af_activateSubform(subformID)

Activates the specified subform. This method accepts either the subform's ID or 0-based index.

Parameters:
{String or Number} subformID: ID of the subform or its 0-based index

af_addSubtableRow(subtableViewName)

Adds a new row at the end of the specified subtable view.

Parameters:
{String} subtableViewName: the name of the subtable view

af_formAbort()

Aborts the form (i.e. the associated step in the process fails). This is the same as clicking on the default Abort-button, except there will be no dialogue asking for confirmation.

{String} af_formatDate(date, datePattern, timePattern)

Formats a Date according to the specified date format, which may represent a date and/or time.

Parameters:
{Date} date: the Date to be formatted
{String} datePattern: the explicit date format pattern (see link below); 'default' for a date according to the user's locale; null or empty string if the Date does not have a date component
{String} timePattern: the explicit time format pattern (see link below); 'default' for a time according to the user's locale; null or empty string if the Date does not have a time component

Returns:: {String} the formatted date

See:: http://www.unicode.org/reports/tr35/#Date_Format_Patterns

{String} af_formatNumber(number, pattern)

Formats a number according to the specified pattern. If the pattern is omitted the number is formatted according to the default pattern of the agent's locale.

Parameters:
{Number} number: the number to be formatted
{String} pattern: the number format pattern (see link below); optional (pattern according to user's locale is then used instead)

Returns:: {String} the formatted number

See:: http://www.unicode.org/reports/tr35/#Number_Format_Patterns

af_formClose()

Closes the form (i.e. its state is discarded). This is the same as clicking on the default Close-button, except there will be no dialogue asking for confirmation.

af_formSend()

Submits the form unless form validation or custom onSubmit scripts prevent it. This is the same as clicking on the default Send-button.

af_formSuspend()

Suspends the form (i.e. saves its state and closes it) unless custom onSuspend scripts prevent it. This is the same as clicking on the default Save-button.

{String} af_getMessage(key, args)

Returns the localised message with the given key. If arguments are given the message will be formatted using them.

Parameters:
{String} key: the key of the desired message
args

Returns:: {String} the localised message

{Number} af_getSelectedIndex(comboBoxName)

Returns the currently selected (0-based) index of the specified combo box.

Parameters:
{String} comboBoxName: name of the combo box control

Returns:: {Number} the currently selected index

{Number} af_getSubtableViewRowCount(subtableViewName)

Returns the current number of rows of the specified subtable view.

Parameters:
{String} subtableViewName: the name of the subtable view

Returns:: {Number} the current number of rows of the specified subtable view

{mixed} af_getValue(controlName, raw)

Returns the parsed (or optionally raw, i.e. as string) current value of the control with the given name. The data type to which the value is parsed depends on the output parameter to which the control is connected. The default is STRING for unconnected controls. If the value could not be parsed, null is returned. In case of radio buttons the value of the currently selected radio button is returned; undefined if none is selected. In case of a check box its value is returned if it is currently checked; undefined otherwise.

Parameters:
{String} controlName: the name of the control
{Boolean} raw: whether the value should be returned raw (i.e. as string) or parsed (optional, default is false)

Returns:: {mixed} the parsed (or optionally raw) value of the control; or null if the value string could not be parsed to the data type of the control

{Boolean} af_hasValue(controlName, raw)

Returns whether the control contains a value. The empty string is not considered as value. If the boolean flag is false, the value has to be also valid, i.e. it must be parsable according to the control's data type.

Parameters:
{String} controlName: the name of the control
{Boolean} raw: (optional, default is true)

Returns:: {Boolean} true if the control has any other value than the empty string; false otherwise

{Boolean} af_isChecked(controlName, radioValue)

Returns whether the specified control (either radio button or check box) is currently checked. For check boxes only the first parameter is required. For radio buttons it is optional. When omitted, the method will return whether *any* radio button of the radio button group is checked. Otherwise the second parameter is the value of the radio button that should be tested.

To set the checked state of a check box or radio button group you may use #af_setValue.

Parameters:
{String} controlName: the name of the control
{String} radioValue: value of the desired radio button which is a string (optional)

Returns:: {Boolean} whether the control is checked

{Boolean} af_isMarkedInvalid(controlName)

Returns whether the control with the specified name is currently marked as invalid. In case of radio button groups true is returned if any member is marked as invalid (which should be all of them if #af_markInvalid was used).

Parameters:
{String} controlName: the name of the control

Returns:: {Boolean} whether the control is currently marked as invalid

{Boolean} af_isOptional(controlName)

Returns whether the input control with the specified name is optional, i.e. whether it requires an input value.

Parameters:
{String} controlName: the name of the control

Returns:: {Boolean} whether the input control with the specified name is optional, i.e. whether it requires an input value

af_makeFormReadOnly()

Makes the complete form read only, disables sub-table buttons.

af_markInvalid(controlName, invalid)

Marks the control with the specified name as being invalid (if second parameter is true or a string). In case of a radio button group all radio button are marked as such. If the second parameter is string, it will be displayed in an appropriate way.

Parameters:
{String} controlName: the name of the control
{mixed} invalid: false marks the control as valid; true or a string marks the control as invalid; a string will be displayed as error message

{Date} af_parseDate(string, datePattern, timePattern)

Parses a date string according to the specified date format, which may represent a date and/or time.

Parameters:
{String} string: the date string to be parsed
{String} datePattern: the explicit date format pattern (see link below); 'default' for a date according to the user's locale; null or empty string if the string does not have a date component
{String} timePattern: the explicit time format pattern (see link below); 'default' for a time according to the user's locale; null or empty string if the string does not have a time component

Returns:: {Date} the parsed Date or null if the string could not be parsed with the pattern

See:: http://www.unicode.org/reports/tr35/#Date_Format_Patterns

{Number} af_parseNumber(string, pattern)

Parses a number string according to the specified number format. If the pattern is omitted the number is parsed according to the default pattern of the agent's locale.

Parameters:
{String} string: the number string to be parsed
{String} pattern: the number format pattern (see link below); optional (pattern according to user's locale is then used instead)

Returns:: {Number} the parsed number or NaN if the string didn't match the pattern

See:: http://www.unicode.org/reports/tr35/#Number_Format_Patterns

af_removeSubform(subformID)

Completely removes the specified subform and all its controls.

Parameters:
{String or Number} subformID: ID of the subform or its 0-based index

af_removeSubtableRow(subtableViewName, row)

Removes the row at the given index in the specified subtable view.

Parameters:
{String} subtableViewName: the name of the subtable view
{Number} row: the 1-based index of the row that should be removed

af_setBackground(controlName, colour)

Sets the background colour of the specified control.

Parameters:
{String} controlName: the name of the control
{String} colour: the desired colour, e.g. #FF0000, red or the empty string to clear the colour

af_setDisabled(controlName, disabled)

Disabled or enables a control. In case of radio button groups (whose members all share the same control name) all its members will receive the new state. Disabled control cannot be changed / edited by the user and their values will not be sent back to the server.

This function also supports subtable views.

Parameters:
{String} controlName: name of the control
{Boolean} disabled: the new state of the disabled-state

af_setGroupBoxCollapsed(groupBoxID, collapsed)

Collapses or expands the specified GroupBox.

Parameters:
{String} groupBoxID: the ID of the GroupBox
{Boolean} collapsed: whether the GroupBox should be collapsed (expanded otherwise)

af_setGroupBoxDisabled(groupBoxID, disabled)

Sets the disabled-state of all controls within the specified group box.

Parameters:
{String} groupBoxID: ID of the group box
{Boolean} disabled: the new state of the disabled-state

See:: af_setDisabled

af_setGroupBoxHidden(groupBoxID, hidden)

Collapses & hides or expands & unhides the specified GroupBox.

Parameters:
{String} groupBoxID: the ID of the GroupBox
{Boolean} hidden: whether the GroupBox should be hidden + collapsed (visible + expanded otherwise)

af_setGroupBoxReadOnly(groupBoxID, readOnly)

Sets the readOnly-state of all controls within the specified group box.

Parameters:
{String} groupBoxID: ID of the group box
{Boolean} readOnly: the new state of the readOnly-state

See:: af_setReadOnly

af_setGroupBoxTitle(groupBoxID, title)

Sets the title of the specified GroupBox to the given title.

Parameters:
{String} groupBoxID: the ID of the GroupBox
{String} title: the new title of the GroupBox

af_setHidden(controlName, hidden)

Hides or unhides a control. In case of radio button groups (whose members all share the same control name) all members will receive the new state. In case of check boxes and radio buttons their labels are included.

Parameters:
{String} controlName: the name of the control
{Boolean} hidden: the new state of the hidden-flag

af_setHiddenAndDisabled(controlName, hiddenAndDisabled)

Combines #af_setHidden and #af_setDisabled.

Parameters:
{String} controlName: the name of the control
{Boolean} hiddenAndDisabled: the new state of the hidden-flag and the disabled-flag

af_setReadOnly(controlName, readOnly)

Sets the readOnly-state of the specified control. In case of radio button groups (whose members all share the same control name) all its members will receive the new state.

This function also supports subtable views.

Please note: Currently, check boxes, radio buttons and combo boxes are disabled because their HTML counter parts to not support a readOnly-flag that makes the control unchangeable to the user.

Parameters:
{String} controlName: name of the control
{Boolean} readOnly: the new state of the readOnly-state

af_setRowBackground(subtableViewName, rowIndex, colour)

Sets the background colour of the specified subtable view row.

Parameters:
{String} subtableViewName: the name of the subtable view
{Number} rowIndex: the 1-based index of the row
{String} colour: the desired colour, e.g. #FF0000, red or the empty string to clear the colour

af_setSelectedIndex(comboBoxName, index, triggerOnChange)

Sets the currently selected (0-based) index of the specified combo box.

By default this function will call the onChange event handler on the combo box, i.e. a change event will be emulated. If this is not desired, the 3rd parameter should be set to false.

Parameters:
{String} comboBoxName: name of the combo box control
{Number} index: the 0-based index of the item that should be selected
{Boolean} triggerOnChange: (optional, default is true)

af_setSubformDisabled(subformID, disabled)

Sets the disabled property for all controls of the specified subform.

Parameters:
{String or Number} subformID: ID of the subform or its 0-based index
{Boolean} disabled: whether the controls of the subform should be disabled

af_setSubformHidden(subformID, hidden)

Hides or shows the specified subform.

Parameters:
{String or Number} subformID: ID of the subform or its 0-based index
{Boolean} hidden: whether the subform should be hidden

af_setSubformReadOnly(subformID, readOnly)

Sets the read-only property for all controls of the specified subform.

Parameters:
{String or Number} subformID: ID of the subform or its 0-based index
{Boolean} readOnly: whether the controls of the subform should be read-only

af_setValue(controlName, value, triggerEventHandlers)

Sets a new value for the control with the given name.

In case of radio buttons, the button which has the given value will be selected, all others deselected; i.e. if none has the given value, all radio buttons will be deselected.

In case of check boxes it will be selected if it has the given value; deselected otherwise. However, true and false may also be used to set the state of a check box. Note that this does not change the value of the checkbox!

Optionally setting the value will trigger an event handler on the control: onclick for check boxes and radio buttons; onchange for all others. Whether the handler is triggered is determined by the parameter triggerEventHandlers.

Parameters:
{String} controlName: the name of the control
value: the new value for the control
{Boolean} triggerEventHandlers: true: event handler will be triggered; false: event handler will NOT be triggered; null/undefined: event handler will only be triggered for check boxes and radio buttons (optional; default is null/undefined)

Overview

Functions