Returns the reference to a form control (form field).

Syntax

sfField(id, index)

Parameters

Name	Type	Mandatory	Description

Name

Type

Mandatory

Description

id

string

yes

Control id of the form control.

index

number

no

Index of the form control. Applicable only if the control is present inside a group control.

The index is a zero-based index.

Applies to

Control type	Applicable	Remarks/Exceptions

Control type	Applicable	Remarks/Exceptions
Input controls	Yes
Layout controls	Yes
Behaviour controls	Yes
Static information controls	Yes

Usage examples

Example 1

Let us assume a form contains a text field TankNumber. The reference to the text field can be obtained using,

sfField('control_tanknumber')

Example 2

Let us assume a form contains a group control QuestionsChecklist with a numeric field CapacityInLitres. The reference to the numeric field in the second row can be obtained using,

sfField('control_capacityinlitres',1)

Here, because the field CapacityInLitres can exist multiple times i.e. for once per row in the group control, it is required to provide the index to refer to the exact field.

In practice, however, this function is used to get the reference to the field in order to perform some actions on the field. These actions are performed using extensions of the function as listed below.

Extensions

.disable(isDisabled)

Disables a form field or enables it based on the parameter.

It is usually applied on controls that respond to events triggered by the user e.g. a button. A disabled field becomes non-interactive and does not respond to user events.

To make an input field non-editable, it is recommended to use readOnly instead.

Parameters

Name	Data type	Mandatory	Description

Name

Data type

Mandatory

Description

isDisabled

true/false

no

Set true to disable the field and false to enable the field.

If no value is passed, it is considered as false and the field is enabled.

A bug has been reported that in a disabled form, .disable(false) cannot enable controls. A workaround is to use isReadOnly(false) instead. See known issues.

Applies to

Control type	Remarks

Control type	Remarks
Layout controls	Applicable to all layout controls except Page break.
Behaviour controls	Applicable to all behaviour controls.
Static information controls	Applicable to all static information controls.

Examples

To make a field non-editable,

sfField('control_tanknumber').disable(true);

To make a non-editable field as editable,

.hide()

Hides a form field from the screen.

If the field being hidden is a container e.g. a Group or a Section, then all field inside the container are hidden.

Applies to

Control type	Remarks

Control type	Remarks
Input controls	Applicable to all input controls.
Layout controls	Applicable to all layout controls except Page break.
Behaviour controls	Applicable to all behaviour controls.
Static information controls	Applicable to all static information controls.

Examples

To hide a field,

.itemCount()

Returns the number of images or files in an image or file control.

Applies to

Applicable only to image and file controls.

Examples

To get the number of images in an image control,

To get the number of files in a file control,

.mandatory(isMandatory)

Makes an input form field mandatory (required) or optional based on the parameter.

A mandatory field prevents the user from saving the form until the user provides some input to the field. This validation is done when the user attempts to save the form (e.g. clicks on the ‘Save’ button).

Parameters

Name	Data type	Mandatory	Description

Name

Data type

Mandatory

Description

isMandatory

true/false

no

Set true to make the field mandatory and false to make the field optional.

If no value is passed, it is considered as false and the field is made optional.

Applies to

Control type	Remarks

Control type	Remarks
Input controls	Applicable to all input controls except Toggle.

Examples

To make a field mandatory,

To make a mandatory field as optional,

.readOnly(isReadonly)

Makes an input form field read-only (non-editable) or editable based on the parameter.

A read-only field cannot be edited by the user. The field, however, is part of the form data and is saved along with the form.

To disable an interactive field e.g. a Button, it is recommended to use disable instead.

Parameters

Name	Data type	Mandatory	Description

Name

Data type

Mandatory

Description

isReadonly

true/false

no

Set true to make the field read-only and false to make the field editable.

If no value is passed, it is considered as false and the field is made editable.

Applies to

Control type	Remarks

Control type	Remarks
Input controls	Applicable to all input controls.

Examples

To make a field non-editable,

To make a non-editable field as editable,

.recordCount(includeUnsavedRecords)

Returns the number of rows in a group control.

Parameters

Name	Data type	Mandatory	Description

Name

Data type

Mandatory

Description

includeUnsavedRecords

true/false

yes

Set true to return the number of records that are visible on screen in the group control. It reflects the changes done by the user that may not have been saved. For example, a user may have added new rows or removed existing rows from the group control, and has not saved the form yet.

Set false to return the number of rows in the group control that are already saved by the user. It excludes any changes done by the user that are not saved.

Applies to

Applicable only to group controls.

Examples

To get the number of rows in a group control (as on screen)

To get the number of rows in a group control (only saved records)

.show()

Makes a hidden form field visible on the screen.

If the field being shown is a container e.g. a Group or a Section, then all fields inside the container become visible, unless the individual field is made hidden.

Applies to

Control type	Remarks

Control type	Remarks
Input controls	Applicable to all input controls.
Layout controls	Applicable to all layout controls except Page break.
Behaviour controls	Applicable to all behaviour controls.
Static information controls	Applicable to all static information controls.

Examples

To make a hidden field visible,

Known issues

Ref #	Issue

Ref #	Issue
	In layout controls, .readOnly() makes the controls (e.g. section, group, form template controls) non-clickable and behaves similar to .disable().
SFAPPS-341	.recordCount(includeUnsavedRecords) does not return counts of items in a group control.
SFAPPS-341	.readOnly() prevents default value expressions from being applied to input fields.
SFAPPS-341	Cursor shown on mouseover of disabled numeric and barcode controls is incorrect.
	When a form is disabled and a control has to be enabled, .disable(false) cannot enable the control. A workaround is to use isReadOnly(false) instead.

Planned changes

Ref #	Change description

Ref #	Change description