RadDataForm: Getting Started

This article will guide you through the process of adding a RadDataForm instance to a page in a {N} + Angular application and using it to edit the properties of a "data item" like this:

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

Adding a DataForm to your page

First thing you need to do in order to use the DataForm in an HTML of your Angular component is to add the built-in Angular 2 directives that come with the nativescript-telerik-ui plugin. For more details take a look at the main "Getting Started" article.

Before adding RadDataForm for NativeScript, make sure you have installed Telerik UI for NativeScript Pro.

After that simply add the RadDataForm tag to the HTML and set its source accordingly:

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

Creating the data model

Now we need to create a data model with the object that we will edit with the help of the DataForm. Add a property in your @Component '.ts' file and initialize it in the ngOnInit method:

import { Component, OnInit } from "@angular/core";
import { Person } from "../data-services/person";

@Component({
    moduleId: module.id,
    selector: "tk-dataform-getting-started",
    templateUrl: "dataform-getting-started.component.html"
})
export class DataFormGettingStartedComponent implements OnInit {
    private _person: Person;

    constructor() {
    }

    ngOnInit() {
        this._person = new Person("John", 23, "john@company.com", "New York", "5th Avenue", 11);
    }

    get person(): Person {
        return this._person;
    }
}
export class Person {
    public name: string;
    public age: number;
    public email: string;
    public city: string;
    public street: string;
    public streetNumber: number;

    constructor(name: string, age: number, email: string, city: string, street: string, streetNumber: number) {
        this.name = name;
        this.age = age;
        this.email = email;
        this.city = city;
        this.street = street;
        this.streetNumber = streetNumber;
    }
}

Note that we have bound the source property to an instance of our 'Person' data object. Now if you run the application, you should see the default editor for each property of the provided data object.

Adjusting the editors

Now that we have bound the DataForm to an data object from our @Component, we may need to fine tune it for example to use editors which may be more appropriate for our scenario.
This can be done by:

  • Declare an TKEntityProperty HTML tag and set the tkDataFormProperty inline directive it
  • After that between the TKEntityProperty HTML tag declare an TKPropertyEditor and set the tkEntityPropertyEditor inline directive to it
<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
  • 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
  • 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

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

You can also make changes of the EntityProperty 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.style.fillColor = "LightBlue";
}