Beginner

Data Object Operations

Every UI component features inner storage for loaded data:

Both of the stores feature common methods, properties and events to work with data items on client side while TreeStore offers extended API for treating data items observing hierarchy.

While manipulating data items, you can:

  • apply methods directly to the Data/TreeStore of the component- $$("list").data. Only some functions require this.
  • apply methods to the component by its ID - $$("list"), which implies addressing data store. Most methods have this pattern.
$$("list").data.each(function(obj){...}); //iterates through items array
 
$$("list").count(); //counts items in the list data store

Each data item object possesses the unique ID, index in the data array and set of properties.

Getting the item object

To get the data item object, you should use the getItem method:

var mylist = webix.ui({
    view:"list", 
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}         
    ]
});     
 
//'item2' variable will contain an object of the related list record
var item2 = mylist.getItem("book2");
 
//you can access data members directly
var title = item2.title;//-> "The Godfather"

Getting the item id

Each data item has its ID defined in the dataset. Knowing item ID you can get to all its properties through an item object (described above).

Table 1 Method(s) for getting the item id
Method Description
id (object) gets the ID of a data item
getFirstId() gets the ID of the first data item (with the "zero" index)
getLastId() gets the ID of the last data item
getNextId (id ) gets the ID of a data item that succeeds the one with the specified ID
getPrevId (id ) gets the ID of a data item that precedes the one with the specified ID
getIdByIndex (index ) gets the item ID by its index
getRange (fromId, toId ) gets an array of IDs in a predefined scope
getIndexRange (fromInd, toInd ) gets an array of IDs in a predefined scope
getFirstChildId (id ) gets ID of the first child of the specified item in the hierarchical tree store
getParentId (id ) gets ID of the parent of the specified item in the hierarchical tree store
getNextSibling (id ) gets ID of the next sibling of the specified item in the hierarchical tree store
getPrevSibling (id ) gets ID of the previous sibling of the specified item in the hierarchical tree store

Getting the item index

Each data item defined in a dataset has an index - the position in the dataset starting from 0.

Table 2 Method(s) for getting the item index
Method Description
getIndexById (id ) gets the item index by its ID
getBranchIndex (id ) gets item index in a specific branch

Checking the existence of an item

To check whether a specific item exists in the data set, you should use the exists method:

var mylist = webix.ui({
    view:"list", 
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}         
    ]
});      
 
mylist.exists("book2");// -> true
mylist.exists("book222");// -> false

Changing the item id

To change the current id of an item, you should use the changeId method:

var mylist = webix.ui({
    view:"list", 
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}         
    ]
});      
 
mylist.data.changeId("book1", "book01");

Changing data properties of an item

To change the current value of some item property, you should use the following technique:

item2 = mylist.getItem("book2");
item2.title = "Star Wars";
 
mylist.refresh();
//or
mylist.updateItem("book2", item2);

Methods refresh and updateItem lead to one and the same result and don't have any specificity.

Manipulations with items in the data set

Table 2 Method(s) and properties for manipulating items in the data set
Method Description
count() returns the count of items in the data set
getVisibleCount() (just for the List component) returns the number of items that can be seen with the current view height
data.each() iterates through the collection of data items
data.order returns an array of IDs of the currently displayable items
data.pull returns the hash of all data items
data.eachChild(id) returns the hash of all children (first-level sub items) of the specified item in the hierarchical dataset
data.eachSubItem(id) returns the hash of all sub-items (regardless of level) of the specified item in the hierarchical dataset
data.eachOpen() returns the hash of all open data items in the hierarchical dataset


Unlike order, the pull property returns all the items whether they are displayed in the component or not.

var mylist = webix.ui({
    view:"list", 
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}         
    ]
}); 
mylist.data.pull["book2"];//-> {id:"book2", title:"The Godfather", year:"1972"} 
 
mylist.data.pull["book2"].title;//-> "The Godfather"
 
mylist.data.pull;
//- >[{id:"book1", title:"The Shawshank Redemption", year:"1994"},
//    {id:"book2", title:"The Godfather",            year:"1972"}]

Iterating data items

To iterate through the collection of data items, you should use the each method of the DataStore class.

var mylist = webix.ui({
    view:"list", 
    ...
    data:[
        {id:"book1", title:"The Shawshank Redemption", year:"1994"},
        {id:"book2", title:"The Godfather",            year:"1972"}         
    ]
});
 
var titles =[];
mylist.data.each(function(obj){ titles.push(obj.title); });
//-> titles=["The Shawshank Redemption", "The Godfather"]

The code is equal to a standard for-loop:

for(i = 0; i<data.length; i++ ){
    titles.push(obj.title);
}

Moving items within the data set(s)

Basically, here we speak about changing item position in the data set. Item position is its index (zero-based numbering).

Table 2 Method for moving items within the data set
Method Description
move(sid, tindex, tobj, tid ) moves the specified item to a new position
moveBottom (id ) moves the specified item to the last position
moveTop (id ) moves the specified item to the first position
moveDown (id, step ) increases the item index and moves the item to the new position
moveUp (id, step ) decreases the item index and moves the item to the new position

Moreover, the move method makes it possible to drag an item from one component instance to another (from one list to another list):

// moves item with id="book1" to the 2nd pos in the same list 
// (remember about 0-based numbering)
mylist.move("book1", 1); 
 
//moves the item with id="book1" to the first position in the "mylist2" 
var id = mylist.move("book1", 0, mylist2);
Back to top