Beginner

Data Object Operations

This article discusses such operations as getting the data item object (item ID, item index), checking the existence of items, iterating items, and several others. To learn more about data loading or methods for adding, deleting, and clearing data, please read the corresponding articles.

Every UI component features inner storage for loaded data:

DataStore - a non-hierarchical (inline) store for List, DataView, DataTable, Chart;
TreeStore - a hierarchical store for Tree, TreeTable and GroupList provided that they are loaded with hierarchical XML or JSON.

Both of the stores feature common methods, properties and events to work with data items on the client side, while TreeStore offers extended API for treating data items observing the 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 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 Item ID

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

ID of the data item can't be set as 0, false, null

**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 the ID of the first child of the specified item in a hierarchical tree store
getParentId (id )	gets the ID of the parent of the specified item in a hierarchical tree store
getNextSibling (id )	gets the ID of the next sibling of the specified item in a hierarchical tree store
getPrevSibling (id )	gets the ID of the previous sibling of the specified item in a hierarchical tree store

Getting 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 the item index in a specific branch

Checking Item Existence

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 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 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 Data Set

**Table 2** Method(s) and properties for manipulating items in the data set
Method	Description
count()	returns the number 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);