RadDataForm: Entity Property

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 customize the editors that are used for each property of the edited object and optionally change their type.

NativeScriptUI-DataForm-Getting-Started-Android NativeScriptUI-DataForm-Getting-Started-iOS

This information is included in the EntityProperty object that is created for each property of the edited object.

Adjusting the editors with xml

One way to change the information about the EntityProperty is to declare these properties in xml. Here's an example:

<df:RadDataForm.properties>
    <df:EntityProperty name="name" displayName="Name" index="0" />
    <df:EntityProperty name="age" displayName="Age" index="1" >
        <df:EntityProperty.editor>
            <df:PropertyEditor type="Number" />
        </df:EntityProperty.editor>
    </df:EntityProperty>
    <df:EntityProperty name="email" displayName="E-Mail" index="2" >
        <df:EntityProperty.editor>
            <df:PropertyEditor type="Email" />
        </df:EntityProperty.editor>
    </df:EntityProperty>
    <df:EntityProperty name="city" displayName="City" index="3" valuesProvider="New York, Washington, Los Angeles">
        <df:EntityProperty.editor>
            <df:PropertyEditor type="Picker" />
        </df:EntityProperty.editor>
    </df:EntityProperty>
    <df:EntityProperty name="street" displayName="Street Name" index="4" />
    <df:EntityProperty name="streetNumber" displayName="Street Number" index="5" >
        <df:EntityProperty.editor>
            <df:PropertyEditor type="Number" />
        </df:EntityProperty.editor>
    </df:EntityProperty>
</df:RadDataForm.properties>

In this example, we have listed all properties of our data item and specified their displayName (the header text for the editor) and their index (in order to ensure that they will be presented in a desired order). Also we have picked an editor for some of the properties. The picker editor allows user to pick one of the values presented as a valuesProvider. More information about the editors, you can find here. Here are all properties of the EntityProperty that you can use to adjust the editors:

  • name - used to specify the name of the property of your data item;
  • displayName - the header text / label of the editor
  • index - a number used to sort the editors
  • columnIndex - a number used to sort the editors which are on the same row when using grid layout
  • hidden - a boolean value indicating whether the current property should be hidden
  • readOnly - a boolean value indicating whether the current property will be editable or will be simply shown in a read only mode
  • required - a boolean value specifying whether the current property is required for the entity to be saved (for example email in a registration form)
  • hintText - a string that will be shown inside the editor when it is empty
  • valuesProvider - a comma-separated list with values that are acceptable for values of the current property
  • converter - a PropertyConverter implementation that is used to convert values from the model to the view and vice versa.
  • editor - a PropertyEditor that allows you to specify the type of the editor that will be used and its styles. More information in the article about editors
  • validators - a list of validators that will be used to validate the value of the editor before setting it to the data item. More information in the article about validation
  • imageResource - the name of an image resource that will be used as a label of the editor. More information in the article about image labels

Now if you run the application, you should get a result like in the image shown in the beginning.

Adjusting the editors with code

Another way to make changes of the EntityProperty is through code. First you need to get the EntityProperty object through the getPropertyByName method and then you can change the values of each property of its properties except from name which is used to correctly link the EntityProperty objects with the properties of the object that is being edited with the data form:

export function changeEditorFill() {
    var property = dataform.getPropertyByName("name");
    property.editor.style.fillColor = "LightBlue";
}
function changeEditorFill() {
    var property = dataform.getPropertyByName("name");
    property.editor.style.fillColor = "LightBlue";
}
exports.changeEditorFill = changeEditorFill;

Adjusting the editors with json

You can also use a json file with similar information to the one included in xml, to setup the editors. Here's an example of json file which setups data form again in the way shown on the first image:

{
"isReadOnly": false,
"commitMode": "immediate",
"validationMode": "immediate",
"propertyAnnotations":
[
{
"name": "name",
"displayName": "Name",
"index": 0
},
{
"name": "age",
"displayName": "Age",
"index": 1,
"editor": "Number"
},
{
"name": "email",
"displayName": "E-Mail",
"index": 2,
"editor": "Email"
},
{
"name": "city",
"displayName": "City",
"index": 3,
"editor": "Picker",
"valuesProvider": ["New York", "Washington", "Los Angeles"]
},
{
"name": "street",
"displayName": "Street Name",
"index": 4
},
{
"name": "streetNumber",
"displayName": "Street Number",
"index": 5,
"editor": "Number"
}
]
}

The parsed content of the file is then given to the dataform through its metadata property:

<df:RadDataForm id="myDataForm" source="{{ person }}" metadata="{{ personMetadata }}"/>

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.