Skip to content

Form Cells

The SDK includes a set of form cells that you use for creating and editing business objects and for building filter controls. All form cells implement the FormCell interface.

The FormCell interface includes methods for getting and setting values, setting the cell type, setting editability, and listening for cell value changes.

Most forms cells also include support for validation by adding a key (label), as well as error or helper text.

FormCell Has Validation Description of Cell
AttachmentFormCell N Pick different files and attach them to the application.
ChoiceFormCell Y Select a single value from a set of values.
DateTimePickerFormCell Y Pick a combination of date and time.
DurationPickerFormCell Y Pick time duration in hours and minutes.
FilterFormCell Y Select one or more values from a small list using chips or check boxes.
FilterChipFormCell Y Select one or more values from a small list using chips.
ListPickerFormCell Y Pick single or multiple options from a long list using radio buttons or check boxes.
NoteFormCell Y Set multi-line text (default: 6 lines) as a note.
SimplePropertyFormCell Y Set a single line of text as a value.
SignatureCaptureFormCell Y Capture a user's signature along with other data such as date and reason for signing.
SignatureCaptureInline Y A scrolling friendly SignatureCaptureFormCell.
SliderFormCell Y Set progress or value on controls, such as volume, using a slider.
SwitchFormCell Y Switch a control on or off in your app.

Editable and Non-Editable Form Cells

FormCells support two different modes: editable and non-editable. You can set these modes using the XML attribute app:editable in a layout, or in code with setEditable(Boolean). The editable attribute changes the behavior of each cell differently. For some form cells such as NoteFormCell and SimplePropertyFormCell, editable has semantic meaning. If NoteFormCell and SimplePropertyFormCells are set app:editable="false", then the cell's value cannot be changed. However, the cell remains enabled, focusable, and selectable. For other form cells, such as DateTimePickerFormCell, AttachmentFormCell and so on, app:editable and android:enabled are the same. For more details about android:enabled, see setEnabled.

Listening for Cell Value Changes

Form cells allow you to listen for value changes. To listen to updates to a cell value, attach a CellValueChangeListener using setCellValueChangeListener.

formcell.setCellValueChangeListener(new FormCell.CellValueChangeListener<T>() {
    @Override
    protected void cellChangeHandler(@NonNull T value) {
        // application code here
    }
});

The type of CellChangeListener varies with the type of form cell:

Form Cell Type of Cell Value
AttachmentFormCell Attachment
ChoiceFormCell Integer
DateTimePickerFormCell Date
DurationPickerFormCell Duration
FilterFormCell List\
FilterChipFormCell List\
ListPickerFormCell List\
NoteFormCell CharSequence
SimplePropertyFormCell CharSequence
SignatureCaptureFormCell SignatureInfo
SignatureCaptureInline SignatureInfo
SliderFormCell Integer
SwitchFormCell Boolean

The attached callback is called whenever there is a change in the cell value. However, you can control the timing of the notification by calling setCellChangeListenerMode(CellChangeListenerMode cellChangeListenerMode) on the listener. CellValueChangeListener currently supports three different modes:

         /**
             * `EditText` change listener mode
             */
            enum CellChangeListenerMode {
                /**
                 * This mode will notify the attached `CellValueChangeListener` before the value of the cell has changed.
                 */
                BEFORE_CELL_CHANGE,
                /**
                 * This mode will notify the attached `CellValueChangeListener` about the changed value of a cell when the value has changed.
                 */
                ON_CELL_CHANGE,
                /**
                 * This mode will notify the attached `CellValueChangeListener` about the changed value of a cell when focus changes.
                 */
                ON_FOCUS_CHANGE
            }

Important

CellChangeListenerModes are not respected by all form cells. For example, with AttachmentFormCell, BEFORE_CELL_CHANGE and ON_FOCUS_CHANGE are not relevant.

Error and Helper Text

Most form cells allow the developer to set error text or helper text to provide hints or feedback to users. To set the error or helper text on the view, enable the feature on the form cell by calling setErrorEnabled or setHelperEnabled, respectively. You can also use app:errorEnabled and app:helperEnabled XML attributes in a layout to enable the support for these features. Once enabled, you can call setError(CharSequence) to set the error text and setHelperText to set the helper text. Once set, the error or helper text remains enabled until setErrorEnabled(false) or setHelperEnabled(false) is called.


Last update: June 15, 2022