Skip to content

The Simple Property Form Cell

The simple property form cell represents a key value cell in which the value is a single-line editable text field. This cell also supports setting helper or error texts.

Using the Simple Property Form Cell

The simple property form cell can be used within your activity like any traditional Android view:

<com.sap.cloud.mobile.fiori.formcell.SimplePropertyFormCell
        android:id="@+id/SimplePropertyFormCell1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:key="Cell key"
        app:value="Cell value" />

Editable and Non-Editable Modes

Like other form cells, this form cell can also be set to be in editable or non-editable mode. When a form cell is set to non-editable, the value field on the cell cannot be edited.

By default, the simple property form cell is editable. You can control the editability of the cell using the app:isEditable="false XML attribute. You can also fetch the view in your activity and set it to be non-editable:

       SimplePropertyFormCell mSimplePropertyCell = findViewById(R.id.simpleproperty_formcell);
       mSimplePropertyCell.setEditable(false);

For more information about the editable attribute, see FormCell.

Error and Helper Texts

To set the error and helper text on the view, call the setErrorEnabled and setHelperEnabled methods, respectively. You can also use app:errorEnabled and app:helperEnabled XML attributes to enable the support for these features. When errors are enabled, an error icon is also added to the end of the value field.

Once enabled, you can call setError(CharSequence) to set the error text and setHelperText(CharSequence) to set the helper text. Once set, the error/helper text remains enabled, until setErrorEnabled(false)/setHelperEnabled(false) is called.

Error and Helper Texts

Text Selectable

The simple property form cell also allows you to enable or disable the ability to select the value text in non-editable states. You can check different variants in action at NoteFormCell Demo.

Listening for Cell Value Changes

To listen for updates to the cell value, attach a CellValueChangeListener<CharSequence> using setCellValueChangeListener:

mSimplePropertyFormCell.setCellValueChangeListener(new FormCell.CellValueChangeListener<CharSequence>() {
            @Override
            protected void cellChangeHandler(@Nullable CharSequence value) {
                if (value.length() > 20) {
                    mSimplePropertyFormCell1.setErrorEnabled(true);
                    mSimplePropertyFormCell1.setError("This value is too long");
                } else {
                    mSimplePropertyFormCell1.setErrorEnabled(false);
                }
            }
        });

Secondary Actions

The simple property form cell provides a button inside the text input box which can invoke various actions. This is accomplished by adding an app:secondaryActionType attribute to your SimplePropertyFormCell layout. You can also call setSecondaryActionType on the simple property form cell. The supported values for secondaryActionType are BARCODE, PASSWORD, and NONE. By default, the NONE action type is set, which initially doesn't display a button, but as you start typing, a Clear button is displayed, which, when clicked, clears the entire input inside the text box. The clear text functionality is also enabled for the BARCODE and PASSWORD action types, or even if you set your own custom action.

Clear Text

The other two supported actions are described in more detail below:

Bar Code Scan Action

The simple property form cell supports scanning a barcode to get relevant information from a barcode as an input. To add bar code scanning support, add an app:secondaryActionType attribute to your layout with the value set to BARCODE:

<com.sap.cloud.mobile.fiori.formcell.SimplePropertyFormCell
        android:id="@+id/SimplePropertyFormCell2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:secondaryActionType="BARCODE"
        app:key="Cell key"
        app:value="Cell value" />

Or, call setSecondaryActionType on your simple property form cell:

mSimplePropertyFormCell2.setSecondaryActionType(BARCODE);

Either approach adds a barcode scan button towards the end of the simple property form cell. When the user taps the Scan button, a scanning activity is launched. The scanner detects the barcode and the extracted information is set as the value of the simple property form cell.

Barcode Scan

Password Visibility Toggle Action

The simple property form cell also provides password visibility toggle functionality to protect any sensitive information that is required to be entered, such as a password. When this action is set, a visibility toggle button is displayed, which, when clicked, toggles the text in the value field to be shown as plain-text if it was disguised or, if it was in plain-text, to be hidden. To enable this, set the app:secondaryActionType attribute in your layout to PASSWORD:

<com.sap.cloud.mobile.fiori.formcell.SimplePropertyFormCell
        android:id="@+id/SimplePropertyFormCell3"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:secondaryActionType="PASSWORD"
        app:key="Cell key"
        app:value="Cell value" />

Or, call setSecondaryActionType on your simple property form cell:

mSimplePropertyFormCell3.setSecondaryActionType(PASSWORD);

Password Visibility Toggle

Custom Action

If you want to add your own custom behavior when the button is tapped, set an icon with the setSecondaryActionIcon(Drawable) method and a content description for it using the setSecondaryActionIconContentDescription(CharSequence) method first, and then override the tap callback with a setSecondaryActionOnClickListener:

mSimplePropertyFormCell4.setSecondaryActionOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        Toast.makeText(mSimplePropertyFormCell.getContext(),
            "Custom secondary action", Toast.LENGTH_SHORT).show();
    }
});

Required Field

You may mark a field as a required field by setting the app:requiredField attribute to true in your XML layout or calling the setRequiredField(boolean) method. This adds an asterisk (*) at the end of the key, which indicates to the user that a value has to be entered. Please note, though, that this is simply a visual indicator and you have to add your own validation to it. See Listening for Cell Value Changes.

Required Field

Prefix and Suffix

A prefix or suffix can also be added to the value using the app:prefixText/app:suffixText attributes in XML or calling the setPrefixText(CharSequence)/setSuffixText(CharSequence) methods, respectively.

Prefix Suffix

See also FormCell


Last update: June 15, 2022