Beginner

Data Loading

After a data component has been initialized, you need to populate it with data in any of the supported formats:

JSON
XML
CSV
JSArray
HTML
Excel
HTMLtable

You can do this in two ways for all the data components:

Loading from an External Resource - a File or a Database
Parsing from a String.

After the data has been loaded or parsed, it is stored in the inner storage for loaded data (DataStore or TreeStore). The url and data properties are merely a source of initial data. For more details, follow the link.

The next step is to use Webix templates to render data within the component.

Defining ID for Data Items

Identifier (or ID for short) is a must-have property for a data item as any interaction with the item is performed via its ID.

Assuming you have a predefined list of squash types and want to update a particular cultivar programmatically. In code it would look like the following:

webix.ui({
    view: "list",
    id: "list1",
    // local data
    data: [
        {id: 1, type: "Butternut Squash", weight: 3},
        {id: 2, type: "Crookneck", weight: 2},
        {id: 3, type: "Pumpkin", weight: 5},
    ]
});
 
// updating a squash with the id of 2
$$("list1").updateItem(2, {weight: 1});

Or if you don't like a particular squash, you can remove it via a dedicated API method:

// squash with the id of 3 will be removed
$$("list1").remove(3);

In both cases you refer to the data items via their IDs.

There are 2 requirements to comply when defining IDs:

Each ID should be unique to avoid possible collisions.
You cannot define the following values as the ID for items:
- 0 (number)
- null
- false (boolean).

Although the mentioned above values themselves are not welcomed and can provoke unexpected behavior, you can leverage them as strings:

data: [
    {
        title: "Mixta",
        id: false,  // NOT OK    },
    {
        title: "Moschata",
        id: "false",  // OK    }
]

If you don't specify ID for a data item, Webix will generate and assign the ID automatically.

Loading from External Resource

To load data from an external file or a database, you should specify the path to this file/or server-side script that fetches the data:

1. As a value of the component's url property. Data will be loaded right after the initialization of the component. The type of incoming data should be specified (if it's not JSON) as well.

{
    view:"list"
    url:"data.xml"
    datatype:"xml"
}

The url property can be a string, a function and an object.

2. As a parameter of the load() method.

$$("mylist").load("data.xml");

The load function has three parameters:

a path to the necessary file or script;
a datatype - in case of JSON data this parameter can be omitted;
a callback function, if needed;

and returns a promise.

$$('component_id').load(".../data.xml", "xml").then(function(data){
    //...your code here
});

Related sample: Form:Loading

It can be called on the necessary page event (button clicking, etc.), as well as on an inner event of the component.

As soon as the component is parsed:

webix.ui({
    view:"list",
    ready:function(){
        this.load("data/books2.xml","xml");
        this.select(this.getFirstId());
    }
});

Loading from an Excel file

While loading data from an Excel file, you should use a proxy object and specify the datatype:"excel". For example:

{ 
    view:"list", 
    url:"binary->files/data.xlsx", 
    datatype:"excel"
}

In the above example the binary proxy is used for loading a file, which allows getting its contents as ArrayBuffer.

Loading via Proxy Objects

You can also set a rather complicated loading pattern in a proxy object that you should pass into the url property or the load() function.

Webix features predefined proxy objects. To learn more about proxy functionality, consult the dedicated article.

view:"list"
url:{
    $proxy:true,
    load: function(view,params){
        return webix.ajax("/data");
    },
    save:function(){
        // ...
    }
}

Furthermore, if a server-side dataset is too big, dynamic loading allows to load a limited quantity of data items first and then load the new data only as you scroll or page through the component.

Note that there's a separate article dedicated to Server-Side Integration. There you'll also find customization patterns for loading from a server.

Setting an Alternative Data Source for a Bound Component

With bound components, you can enable data loading not from the master component (as expected by default), but directly from the server.

{
    view:"list"
    url:"data/list.php" // the default data source
},
{
    view:"form",
    id:"form11",
    // ...
    dataFeed: "data/form.php" //a data source for the form only
}
 
// the form takes data from a selected record in the list
$$("form1").bind($$("list1"));

Loading Messages

Webix provides info boxes that are laid over the component for a while to display the desired data, e.g.:

to inform users that the data are being loaded (in case of big datasets);
to inform users that there's no data for this component.

Webix DataTable includes info messages in the form of overlay boxes with any text or html content:

dtable.showOverLay("Loading");
dtable.hideOverlay();

Related sample: Loading Screen

More info on datatable loading screen support.

For other components, you can define Overlay Boxes and Progress Bar (Progress Icon) with the help of the dedicated modules.

// or "this" pointer if the method is called within the component
webix.extend($$("list1"), webix.OverlayBox);
 
webix.ui({
    view:"list",
    id:"list1",
    url:"...",
    ready:function(){
        if (!this.count()){ // if no data are available
            webix.extend(this, webix.OverlayBox);
            this.showOverlay("<div style='...'>There is no data</div>");
        }
    }
});

Related sample: Empty List

More info on overlay boxes and progress bar

Data Loading Events

Webix offers the following events to control the beginning and the end of the loading process:

onBeforeLoad - fires when XML data loading begins;
onAfterLoad - fires when XML data loading is complete;
onStoreLoad - fires when raw external data are fully loaded (regardless of the data type).

mygrid.attachEvent("onAfterLoad", function(){
    webix.message("Data loaded");
})

Related sample: Loading Screen

If something goes wrong with loading, learn how to handle errors on the client side in the Processing loading errors article.

Parsing

Here the data in supported formats comes as is (string or array).

First, it may be the value of the data parameter.

JSON array within the DataView object

webix.ui({
    view:"dataview",
    template:"#title# Year: #year#, rank: #rank#",
    data:[
        { id:1, title:"The Shawshank Redemption", year:1994, rank:1},
        { id:2, title:"The Godfather", year:1972,  rank:2},
        { id:3, title:"The Godfather: Part II", year:1974, rank:3}
    ]
});

JSON object is stored in a variable declared beforehand

var tabledata = [
    { id:1, title:"The Shawshank Redemption", year:1994, rank:1},
    { id:2, title:"The Godfather", year:1972,  rank:2},
    { id:3, title:"The Godfather: Part II", year:1974, rank:3},
    { id:3, title:"The Godfather: Part II", year:1974, rank:3}
];
 
webix.ui({
    view:"dataview",
    template:"#title# Year: #year#, rank: #rank#",
    data: tabledata
});

The variable may be declared either in the same file or in an external js-file you refer to in the document's head.

Second, data can be parsed with the help of the parse() method that takes the data and the datatype as parameters.

Data Parsing from XML string

webix.ui({
    view:"dataview",
    id:"dataview",
    datatype:"xml"
});
 
// the function is executed on a predefined event, e.g. on a button click
 
function parse(){
   var str = "<data>
      <item id='10'><title>The Lord of the Rings</title>
      <year>2003</year><rank>10</rank></item>
      </data>";
   $$("dataview").clearAll();
   $$("dataview").parse(str,"xml");
}

Related sample: Dataview:XML Dataset

If you want to parse data in addition to the existing dataset, specify the position of parsing, namely the index from which you insert new data:

$$("datatable").parse({
    pos: $$("datatable").count(), //number of records will be right the last index +1
    data:dataset
});

Data Parsing Events

onParse - fires when a component has received inline data and is ready for usage:

dtable.data.attachEvent("onParse", function(driver, data){
    // for json data
    webix.message("Count of records "+data.length);
});

To trigger the event for the component DataStore, handle attachEvent method or define on
(prefixed by "data->") property.

Promise API in Data Loading

Webix is integrated with the Promiz.js library to treat the result of asynchronous operations (like data loading) without callbacks.

It means that any Ajax request returns a promise object than can be treated with Promiz.js API.

"Promise" object is returned by either of these methods

var promise = grid.load("my.php");
var promise = webix.ajax("my.php");
var promise = webix.ajax().get("my.php");
var promise = webix.ajax().post("my.php");

Bonuses

You may process the result of a request in the Promiz.js way without callbacks:

promise.then(function(realdata){
    //success
}).fail(function(err){
    //error
}).finally(function(){
    //any result
});

You can "parse" promise objects directly into the component:

list.parse(webix.ajax("my.php"));

The data will be parsed the moment it comes from the server.

You can make use of the waitData property each data component is supplied with and apply Promiz.js methods to it:

//"promise" approach
grid.waitData.then(function(){
    // when we have data - do some actions
    grid.select(grid.getFirstId());
});

Alternatively, Webix onAfterLoad event can be used:

//standard approach
grid.attachEvent("onAfterLoad", function(){
    // when we have data - do some actions
});