RadDataForm: Editors

If you followed the getting started article, you now know how to edit an object's properties with DataForm for NativeScript. This article will explain how to change the editor that is used for a property and what are the editors supported by RadDataForm and how to use them.

NativeScriptUI-DataForm-Editors-Android NativeScriptUI-DataForm-Editors-iOS

Editor usage

By default RadDataForm will load a default editor depending on the type of each property. If you need to change the type, you can provide another editor through the xml. Here's an example:

<df:EntityProperty name="type" displayName="Type" index="3" valuesProvider="2D, 3D">
    <df:EntityProperty.editor>
        <df:PropertyEditor type="SegmentedEditor" />
    </df:EntityProperty.editor>
</df:EntityProperty>

You can also change the editor through code:

export function changeEditor() {
    var property = dataform.getPropertyByName("age");
    var propertyEditor = new dataFormModule.PropertyEditor();
    propertyEditor.type = "Slider";
    property.editor = propertyEditor;
}

Note that the valuesProvider property will be taken into consideration only for editors that support predefined list of values. These editors are Picker, SegmentedEditor and List.

Editor converters

In the previous example the valuesProvider property was set to an array of strings and the value of the property that they edit is also of type string. In some scenarios you will need to store a value which differs from the one that an editor displays. Consider the following example where you have a class Movie with two properties - name and id. If you want to save only an id and still display a name in an editor, you can create a converter that will convert between the two types. Here's a sample implementation of the aforementioned scenario:

export class TicketViewModel implements dataFormModule.PropertyConverter {
    // ...
    convertFrom(id: number) {
        return this.movies.filter((movie: Movie) => movie.id == id)[0].name;
    }

    convertTo(name: string) {
        return this.movies.filter((movie: Movie) => movie.name == name)[0].id;
    }
}

export class Movie {
    public id: number;
    public name: string;

    constructor(id: number, name: string) {
        this.id = id;
        this.name = name;
    }
}

export class TicketOrder {
    public movie: number = 123;
    // ...
}

As you can see in your model you can have a property of type number which then gets converted to the name of the movie with the same id. Similarly, when another item is selected from the list, its value is converted to id that gets committed. An instance of the created converter then gets set to the converter property of the EntityProperty object.

Editors list

The image in the beginning shows some of the editors of RadDataForm, here's the full list:

  • Text - simple text input
  • MultilineText - text input, which supports more than one line
  • Email - again for text input, with email optimized keyboard
  • Password - masks the entered text
  • Phone - again for text input, with phone optimized keyboard
  • Number - for input of numbers from the keyboard
  • Decimal - for input of numbers from the keyboard, supports decimal values
  • Switch - for boolean values
  • Stepper - for choosing a number by tapping on buttons to increase or decrease it
  • Slider - for choosing a number by sliding between the minimum and maximum values
  • Picker - for picking a value from a predefined list (drop-down list)
  • SegmentedEditor - for picking a value from a predefined list (horizontal list)
  • List - for picking a value from a predefined list (vertical list)
  • DatePicker - for picking a date from a calendar
  • TimePicker - for picking a time from a clock
  • AutoCompleteInline - for picking single or multiple items from a suggestion list

Editor parameters

The Stepper and Slider editors have additional properties which you can setup through PropertyEditorParams. Here's an example with the Stepper editor which limits its bounds and defines its step:

<df:PropertyEditor type="Stepper">
    <df:PropertyEditor.params>
        <df:PropertyEditorParams minimum="2" maximum="6" step="1"/>
    </df:PropertyEditor.params>
</df:PropertyEditor>

Custom editors

If an editor that you would like to use is not included in the list with predefined editors, you can provide your own native view that will be used with the existing editor logic. You can read more here.

Using the 'AutoCompleteInline' editor

The 'autoCompleteDisplayMode'

The AutoCompleteInline editor is a bit more complex then the other built-in editors because it allows for a single editor to handle both single and multiple 'selection' of the EntityProperty property. This means that you can either use this editor for properties of string type or for properties of string[] arrays. This feature is controlled via the autoCompleteDisplayMode property which can be set to AutoCompleteDisplayMode.

How to set the 'suggestions' source

In order for the AutoCompleteInline editor to be able to populate its suggestion box an outside source needs to be provided ot the editor. This is done via the valuesProvider property as with many other 'picker' type editors. The next code snippet shows how you can setup the AutoCompleteInline in the XML of your NativeScript application, the 'data context' of the {N} page has two properties booking and fromProviders, the booking is the object used as source of the RadDataForm itself and the fromProviders is a simple Array<String> contains the 'suggestions' that will be used by the AutoCompleteInline editor. You can set the valuesProvider both statically via XML or via a binding.

<df:RadDataForm source="{{ booking }}">

    <df:RadDataForm.properties>
        <df:EntityProperty name="from" displayName="From:" index="0" autoCompleteDisplayMode="tokens" valuesProvider="{{ fromProviders }}">

            <df:EntityProperty.editor>
                <df:PropertyEditor type="AutoCompleteInline" />
            </df:EntityProperty.editor>
        </df:EntityProperty>

         <df:EntityProperty name="to" displayName="To:" index="1" autoCompleteDisplayMode="plain" valuesProvider="New York, Washington, Los Angeles">
            <df:EntityProperty.editor>
                <df:PropertyEditor type="AutoCompleteInline" />
            </df:EntityProperty.editor>
        </df:EntityProperty>
    </df:RadDataForm.properties>
</df:RadDataForm>

References

Want to see this scenario in action?
Check our SDK examples repo on GitHub. You will find this and many other practical examples with NativeScript UI.

Related articles you might find useful: