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.