Skip to content

Introduction

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.

Form Cells in the SDK

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
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
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 the 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 DateTimePikcerFormCell, 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.

1
2
3
4
5
6
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\
ListPickerFormCell List\
NoteFormCell CharSequence
SimplePropertyFormCell CharSequence
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
         /**
             * 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 on the value of the cell has changed
                 */
                ON_CELL_CHANGE,
                /**
                 * This mode will notify the attached CellValueChangeListener on the change value of 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 relevent.

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.