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 html

One way to change the information about the EntityProperty is to declare these properties in html. In order to do this, you need to declare a TKEntityProperty HTML tag and set the tkDataFormProperty inline directive in it. If you want to change the editor that is used for a specific property, you can declare an TKPropertyEditor and set the tkEntityPropertyEditor inline directive to it within the TKEntityProperty HTML tag. Here's an example:

<TKEntityProperty tkDataFormProperty name="name" displayName="Name" index="0"></TKEntityProperty>
<TKEntityProperty tkDataFormProperty name="age" displayName="Age" index="1">
    <TKPropertyEditor tkEntityPropertyEditor type="Number"></TKPropertyEditor>
</TKEntityProperty>
<TKEntityProperty tkDataFormProperty name="email" displayName="E-Mail" index="2">
    <TKPropertyEditor tkEntityPropertyEditor type="Email"></TKPropertyEditor>
</TKEntityProperty>
<TKEntityProperty tkDataFormProperty name="city" displayName="City" index="3" valuesProvider="New York, Washington, Los Angeles">
    <TKPropertyEditor tkEntityPropertyEditor type="Picker"></TKPropertyEditor>
</TKEntityProperty>
<TKEntityProperty tkDataFormProperty name="street" displayName="Street Name" index="4"></TKEntityProperty>
<TKEntityProperty tkDataFormProperty name="streetNumber" displayName="Street Number" index="5">
    <TKPropertyEditor tkEntityPropertyEditor type="Number"></TKPropertyEditor>
</TKEntityProperty>

In this example, we have listed all properties of our data object 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:

public changeEditorFill() {
    var property = this.myRuntimeDataFormComp.dataForm.getPropertyByName("name");
    property.editor.propertyEditorStyle.fillColor = "LightBlue";
}

Adjusting the editors with json

You can also use a json file with similar information to the one included in html, 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:

<RadDataForm tkExampleTitle tkToggleNavButton [source]="person" [metadata]="personMetadata"></RadDataForm>

Here's a list with the acceptable keys inside the propertyAnnotations array:

  • name - used to specify the name of the property of your data item;
  • displayName - the header text / label of the editor
  • groupName - a string used to specify the name of the group where this property has to be included
  • index - a number used to sort the editors
  • ignore - 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
  • editor - a PropertyEditor that allows you to specify the type of the editor that will be used. More information in the article about editors
  • editorParams - list of key-value pairs that allows you to setup the editor that is used. The acceptable keys are step (used when the editor is of type Stepper), min and max (used when the editor is of type Stepper or Slider)
  • valuesProvider - a comma-separated list with values that are acceptable for values of the current property

References

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

Related articles you might find useful: