DataStore

class webix.DataStore()

Datastore mixin

References

mixins

DataDriver(), EventSystem().

helpers

assert(), bind(), copy(), extend(), isArray(), isUndefined(), log(), toArray(), uid().

Referenced by

components

DataLoader().

External references

Official documentation page.

Code

webix.DataStore = function(){
    this.name = "DataStore";

    webix.extend(this, webix.EventSystem);

    this.setDriver("json");    //default data source is an
    this.pull = {};                        //hash of IDs
    this.order = webix.toArray();        //order of IDs
    this._marks = {};
};

webix.DataStore.prototype={
    //defines type of used data driver
    //data driver is an abstraction other different data formats - xml, json, csv, etc.
    setDriver:function(type){
        webix.assert(webix.DataDriver[type],"incorrect DataDriver");
        this.driver = webix.DataDriver[type];
    },
    //process incoming raw data
    _parse:function(data,master){
        this.callEvent("onParse", [this.driver, data]);

        if (this._filter_order)
            this.filter();

        //get size and position of data
        var info = this.driver.getInfo(data);

        //generated by connectors only
        if (info.key)
            webix.securityKey = info.key;

        if (info.config)
            this.callEvent("onServerConfig",[info.config]);

        var options = this.driver.getOptions(data);
        if (options)
            this.callEvent("onServerOptions", [options]);

        //get array of records
        var recs = this.driver.getRecords(data);

        this._inner_parse(info, recs);

        //in case of tree store we may want to group data
        if (this._scheme_group && this._group_processing && !this._not_grouped_order)
            this._group_processing(this._scheme_group);

        //optional data sorting
        if (this._scheme_sort){
            this.blockEvent();
            this.sort(this._scheme_sort);
            this.unblockEvent();
        }

        this.callEvent("onStoreLoad",[this.driver, data]);
        //repaint self after data loading
        this.refresh();
    },
    _inner_parse:function(info, recs){
        var from = (info.from||0)*1;
        var subload = true;
        var marks = false;

        if (from === 0 && this.order[0] && this.order[this.order.length-1]){ //update mode
            if (this._removeMissed){
                //update mode, create kill list
                marks = {};
                for (var i=0; i<this.order.length; i++)
                    marks[this.order[i]]=true;
            }

            subload = false;
            from = this.order.length;
        }

        var j=0;
        for (var i=0; i<recs.length; i++){
            //get hash of details for each record
            var temp = this.driver.getDetails(recs[i]);
            var id = this.id(temp);     //generate ID for the record
            if (!this.pull[id]){        //if such ID already exists - update instead of insert
                this.order[j+from]=id;
                j++;
            } else if (subload && this.order[j+from])
                j++;

            if(this.pull[id]){
                webix.extend(this.pull[id],temp,true);//add only new properties
                if (this._scheme_update)
                    this._scheme_update(this.pull[id]);
                //update mode, remove item from kill list
                if (marks)
                    delete marks[id];
            } else{
                this.pull[id] = temp;
                if (this._scheme_init)
                    this._scheme_init(temp);
            }

        }

        //update mode, delete items which are not existing in the new xml
        if (marks){
            this.blockEvent();
            for (var delid in marks)
                this.remove(delid);
            this.unblockEvent();
        }

        if (!this.order[info.size-1])
            this.order[info.size-1] = webix.undefined;
    },
    //generate id for data object
    id:function(data){
        return data.id||(data.id=webix.uid());
    },
    changeId:function(old, newid){
        //webix.assert(this.pull[old],"Can't change id, for non existing item: "+old);
        if(this.pull[old])
            this.pull[newid] = this.pull[old];

        this.pull[newid].id = newid;
        this.order[this.order.find(old)]=newid;
        if (this._filter_order)
            this._filter_order[this._filter_order.find(old)]=newid;
        if (this._marks[old]){
            this._marks[newid] = this._marks[old];
            delete this._marks[old];
        }


        this.callEvent("onIdChange", [old, newid]);
        if (this._render_change_id)
            this._render_change_id(old, newid);
        delete this.pull[old];
    },
    //get data from hash by id
    getItem:function(id){
        return this.pull[id];
    },
    //assigns data by id
    updateItem:function(id, update, mode){
        var data = this.getItem(id);
        var old = null;

        //check is change tracking active
        var changeTrack = this.hasEvent("onDataUpdate");

        webix.assert(data, "Ivalid ID for updateItem");
        webix.assert(!update || !update.id || update.id == id, "Attempt to change ID in updateItem");
        if (!webix.isUndefined(update) && data !== update){
            //preserve original object
            if (changeTrack)
                old = webix.copy(data);

            id = data.id;    //preserve id
            webix.extend(data, update, true);
            data.id = id;
        }

        if (this._scheme_update)
            this._scheme_update(data);

        this.callEvent("onStoreUpdated",[id.toString(), data, (mode||"update")]);

        if (changeTrack)
            this.callEvent("onDataUpdate", [id, data, old]);
    },
    //sends repainting signal
    refresh:function(id){
        if (this._skip_refresh) return;

        if (id){
            if (this.exists(id))
                this.callEvent("onStoreUpdated",[id, this.pull[id], "paint"]);
        }else
            this.callEvent("onStoreUpdated",[null,null,null]);
    },
    silent:function(code, master){
        this._skip_refresh = true;
        code.call(master||this);
        this._skip_refresh = false;
    },
    //converts range IDs to array of all IDs between them
    getRange:function(from,to){
        //if some point is not defined - use first or last id
        //BEWARE - do not use empty or null ID
        if (from)
            from = this.getIndexById(from);
        else
            from = (this.$min||this.startOffset)||0;
        if (to)
            to = this.getIndexById(to);
        else {
            to = this.$max === 0 ? 0 : Math.min((this.$max?this.$max-1:(this.endOffset||Infinity)),(this.count()-1));
            if (to<0) to = 0; //we have not data in the store
        }

        if (from>to){ //can be in case of backward shift-selection
            var a=to; to=from; from=a;
        }

        return this.getIndexRange(from,to);
    },
    //converts range of indexes to array of all IDs between them
    getIndexRange:function(from,to){
        to=Math.min((to === 0 ? 0 :(to||Infinity)),this.count()-1);

        var ret=webix.toArray(); //result of method is rich-array
        for (var i=(from||0); i <= to; i++)
            ret.push(this.getItem(this.order[i]));
        return ret;
    },
    //returns total count of elements
    count:function(){
        return this.order.length;
    },
    //returns truy if item with such ID exists
    exists:function(id){
        return !!(this.pull[id]);
    },
    //nextmethod is not visible on component level, check DataMove.move
    //moves item from source index to the target index
    move:function(sindex,tindex){
        webix.assert(sindex>=0 && tindex>=0, "DataStore::move","Incorrect indexes");
        if (sindex == tindex) return;

        var id = this.getIdByIndex(sindex);
        var obj = this.getItem(id);

        if (this._filter_order)
            this._move_inner(this._filter_order, 0, 0, this.getIdByIndex(sindex), this.getIdByIndex(tindex));

        this._move_inner(this.order, sindex, tindex);


        //repaint signal
        this.callEvent("onStoreUpdated",[id,obj,"move"]);
    },
    _move_inner:function(col, sindex, tindex, sid, tid){
        if (sid||tid){
            sindex = tindex = -1;
            for (var i=0; i<col.length; i++){
                if (col[i] == sid && sindex<0)
                    sindex = i;
                if (col[i] == tid && tindex<0)
                    tindex = i;
            }
        }
        var id = col[sindex];
        col.removeAt(sindex);    //remove at old position
        col.insertAt(id,Math.min(col.length, tindex));    //insert at new position
    },
    scheme:function(config){
        this._scheme = {};
        this._scheme_save = config.$save;
        this._scheme_init = config.$init||config.$change;
        this._scheme_update = config.$update||config.$change;
        this._scheme_serialize = config.$serialize;
        this._scheme_group = config.$group;
        this._scheme_sort = config.$sort;

        //ignore $-starting properties, as they have special meaning
        for (var key in config)
            if (key.substr(0,1) != "$")
                this._scheme[key] = config[key];
    },
    importData:function(target, silent){
        var data = target ? (target.data || target) : [];
        this._filter_order = null;

        if (typeof data.serialize == "function"){
            this.order = webix.toArray([].concat(data.order));
            this.pull = data.pull;
            if (data.branch && this.branch){
                this.branch = webix.copy(data.branch);
                this._filter_branch = null;
            }

        } else {
            this.order = webix.toArray();
            this.pull = {};
            var id, obj;

            if (webix.isArray(target))
                for (var key=0; key<target.length; key++){
                    obj = id = target[key];
                    if (typeof obj == "object")
                        obj.id  = obj.id || webix.uid();
                    else
                        obj = { id:id, value:id };

                    this.order.push(obj.id);
                    if (this._scheme_init)
                        this._scheme_init(obj);
                    this.pull[obj.id] = obj;
                }
            else
                for (var key in data){
                    this.order.push(key);
                    this.pull[key] = { id:key, value: data[key] };
                }
        }
        if (this._extraParser && !data.branch){
            this.branch = { 0:[]};
            if (!this._datadriver_child)
                this._set_child_scheme("data");

            for (var i = 0; i<this.order.length; i++){
                var key = this.order[i];
                this._extraParser(this.pull[key], 0, 0, false);
            }
        }

        this.callEvent("onStoreLoad",[]);
        if (!silent)
            this.callEvent("onStoreUpdated",[]);
    },
    sync:function(source, filter, silent){
        var type = typeof source;
        if (type == "string")
            source = webix.$$("source");

        if (type != "function" && type != "object"){
            silent = filter;
            filter = null;
        }

        if (webix.debug_bind){
            this.debug_sync_master = source;
            webix.log("[sync] "+this.debug_bind_master.name+"@"+this.debug_bind_master._settings.id+" <= "+this.debug_sync_master.name+"@"+this.debug_sync_master._settings.id);
        }

        if (source.name != "DataStore"){
            if (source.data && (source.data.name === "DataStore" || source.data.name === "TreeStore"))
                source = source.data;
            else {
                this._sync_source = source;
                return webix.callEvent("onSyncUnknown", [this, source, filter]);
            }
        }

        var    sync_logic = webix.bind(function(mode, record, data){
            if (this._skip_next_sync) return;

            this.importData(source, true);

            if (filter)
                this.silent(filter);
            if (this._on_sync)
                this._on_sync();

            if (webix.debug_bind)
                webix.log("[sync:request] "+this.debug_sync_master.name+"@"+this.debug_sync_master._settings.id + " <= "+this.debug_bind_master.name+"@"+this.debug_bind_master._settings.id);

            this.callEvent("onSyncApply",[]);

            if (!silent)
                this.refresh();
            else
                silent = false;
        }, this);



        this._sync_events = [
            source.attachEvent("onStoreUpdated", sync_logic),
            source.attachEvent("onIdChange", webix.bind(function(old, nid){ this.changeId(old, nid); this.refresh(nid); }, this))
        ];
        this._sync_source = source;

        //backward data saving
        this._back_sync_handler = this.attachEvent("onStoreUpdated", function(id, data, mode){
            if (mode == "update" || mode == "save"){
                this._skip_next_sync = 1;
                source.updateItem(id, data);
                this._skip_next_sync = 0;
            }
        });

        sync_logic();
    },
    unsync:function(){
        if (this._sync_source){
            var source = this._sync_source;

            if (source.name != "DataStore" &&
                    (!source.data || source.data.name != "DataStore")){
                //data sync with external component
                webix.callEvent("onUnSyncUnknown", [this, source]);
            } else {
                //data sync with webix component
                for (var i = 0; i < this._sync_events.length; i++)
                    source.detachEvent(this._sync_events[i]);
                this.detachEvent(this._back_sync_handler);
            }

            this._sync_source = null;
        }
    },
    destructor:function(){
        this.unsync();

        this.pull = this.order = this._marks = null;
        this._evs_events = this._evs_handlers = {};
    },
    //adds item to the store
    add:function(obj,index){
        //default values
        if (this._scheme)
            for (var key in this._scheme)
                if (webix.isUndefined(obj[key]))
                    obj[key] = this._scheme[key];

        if (this._scheme_init)
            this._scheme_init(obj);

        //generate id for the item
        var id = this.id(obj);

        //in case of treetable order is sent as 3rd parameter
        var order = arguments[2]||this.order;

        //by default item is added to the end of the list
        var data_size = order.length;

        if (webix.isUndefined(index) || index < 0)
            index = data_size;
        //check to prevent too big indexes
        if (index > data_size){
            webix.log("Warning","DataStore:add","Index of out of bounds");
            index = Math.min(order.length,index);
        }
        if (this.callEvent("onBeforeAdd", [id, obj, index]) === false) return false;

        webix.assert(!this.exists(id), "Not unique ID");

        this.pull[id]=obj;
        order.insertAt(id,index);
        if (this._filter_order){    //adding during filtering
            //we can't know the location of new item in full dataset, making suggestion
            //put at end of original dataset by default
            var original_index = this._filter_order.length;
            //if some data exists, put at the same position in original and filtered lists
            if (this.order.length)
                original_index = Math.min((index || 0), original_index);

            this._filter_order.insertAt(id,original_index);
        }

        //repaint signal
        this.callEvent("onStoreUpdated",[id,obj,"add"]);
        this.callEvent("onAfterAdd",[id,index]);

        return obj.id;
    },

    //removes element from datastore
    remove:function(id){
        //id can be an array of IDs - result of getSelect, for example
        if (webix.isArray(id)){
            for (var i=0; i < id.length; i++)
                this.remove(id[i]);
            return;
        }
        if (this.callEvent("onBeforeDelete",[id]) === false) return false;

        webix.assert(this.exists(id), "Not existing ID in remove command"+id);

        var obj = this.getItem(id);    //save for later event
        //clear from collections
        this.order.remove(id);
        if (this._filter_order)
            this._filter_order.remove(id);

        delete this.pull[id];
        if (this._marks[id])
            delete this._marks[id];

        //repaint signal
        this.callEvent("onStoreUpdated",[id,obj,"delete"]);
        this.callEvent("onAfterDelete",[id]);
    },
    //deletes all records in datastore
    clearAll:function(){
        //instead of deleting one by one - just reset inner collections
        this.pull = {};
        this._marks = {};
        this.order = webix.toArray();
        //this.feed = null;
        this._filter_order = this.url = null;
        this.callEvent("onClearAll",[]);
        this.refresh();
    },
    //converts id to index
    getIdByIndex:function(index){
        webix.assert(index >= 0,"DataStore::getIdByIndex Incorrect index");
        return this.order[index];
    },
    //converts index to id
    getIndexById:function(id){
        var res = this.order.find(id);    //slower than getIdByIndex
        if (!this.pull[id])
            return -1;

        return res;
    },
    //returns ID of next element
    getNextId:function(id,step){
        return this.order[this.getIndexById(id)+(step||1)];
    },
    //returns ID of first element
    getFirstId:function(){
        return this.order[0];
    },
    //returns ID of last element
    getLastId:function(){
        return this.order[this.order.length-1];
    },
    //returns ID of previous element
    getPrevId:function(id,step){
        return this.order[this.getIndexById(id)-(step||1)];
    },
    /*
        sort data in collection
            by - settings of sorting

        or

            by - sorting function
            dir - "asc" or "desc"

        or

            by - property
            dir - "asc" or "desc"
            as - type of sortings

        Sorting function will accept 2 parameters and must return 1,0,-1, based on desired order
    */
    sort:function(by, dir, as){
        var sort = by;
        if (typeof by == "function")
            sort = {as:by, dir:dir};
        else if (typeof by == "string")
            sort = {by:by.replace(/#/g,""), dir:dir, as:as};


        var parameters = [sort.by, sort.dir, sort.as, sort];
        if (!this.callEvent("onBeforeSort",parameters)) return;

        this.order = this._sort_core(sort, this.order);
        if (this._filter_order && this._filter_order.length != this.order.length)
            this._filter_order = this._sort_core(sort, this._filter_order);

        //repaint self
        this.refresh();

        this.callEvent("onAfterSort",parameters);
    },
    _sort_core:function(sort, order){
        var sorter = this.sorting.create(sort);
        if (this.order.length){
            var pre = order.splice(0, this.$freeze);
            //get array of IDs
            var neworder = webix.toArray();
            for (var i=order.length-1; i>=0; i--)
                neworder[i] = this.pull[order[i]];

            neworder.sort(sorter);
            return webix.toArray(pre.concat(neworder.map(function(obj){
                webix.assert(obj, "Client sorting can't be used with dynamic loading");
                return this.id(obj);
            },this)));
        }
        return order;
    },
    /*
        Filter datasource

        text - property, by which filter
        value - filter mask

        or

        text  - filter method

        Filter method will receive data object and must return true or false
    */
    _filter_reset:function(preserve){
        //remove previous filtering , if any
        if (this._filter_order && !preserve){
            this.order = this._filter_order;
            delete this._filter_order;
        }
    },
    _filter_core:function(filter, value, preserve){
        var neworder = webix.toArray();
        var freeze = this.$freeze || 0;

        for (var i=0; i < this.order.length; i++){
            var id = this.order[i];
            if (i < freeze || filter(this.getItem(id),value))
                neworder.push(id);
        }
        //set new order of items, store original
        if (!preserve ||  !this._filter_order)
            this._filter_order = this.order;
        this.order = neworder;
    },
    find:function(config, first){
        var result = [];

        for(var i in this.pull){
            var data = this.pull[i];

            var match = true;
            if (typeof config == "object"){
                for (var key in config)
                    if (data[key] != config[key]){
                        match = false;
                        break;
                    }
            } else if (!config(data))
                match = false;

            if (match)
                result.push(data);

            if (first && result.length)
                return result[0];
        }

        return result;
    },
    filter:function(text,value,preserve){
        //unfilter call but we already in not-filtered state
        if (!text && !this._filter_order && !this._filter_branch) return;
        if (!this.callEvent("onBeforeFilter", [text, value])) return;

        this._filter_reset(preserve);
        if (!this.order.length) return;

        //if text not define -just unfilter previous state and exit
        if (text){
            var filter = text;
            value = value||"";
            if (typeof text == "string"){
                text = text.replace(/#/g,"");
                if (typeof value == "function")
                    filter = function(obj){
                        return value(obj[text]);
                    };
                else{
                    value = value.toString().toLowerCase();
                    filter = function(obj,value){    //default filter - string start from, case in-sensitive
                        webix.assert(obj, "Client side filtering can't be used with dynamic loading");
                        return (obj[text]||"").toString().toLowerCase().indexOf(value)!=-1;
                    };
                }
            }

            this._filter_core(filter, value, preserve, this._filterMode);
        }
        //repaint self
        this.refresh();

        this.callEvent("onAfterFilter", []);
    },
    /*
        Iterate through collection
    */
    _obj_array:function(){
        var data = [];
        for (var i = this.order.length - 1; i >= 0; i--)
            data[i]=this.pull[this.order[i]];

        return data;
    },
    each:function(method, master, all){
        var order = this.order;
        if (all)
            order = this._filter_order || order;

        for (var i=0; i<order.length; i++)
            method.call((master||this), this.getItem(order[i]), i);
    },
    _methodPush:function(object,method){
        return function(){ return object[method].apply(object,arguments); };
    },
    /*
        map inner methods to some distant object
    */
    provideApi:function(target,eventable){
        this.debug_bind_master = target;

        if (eventable){
            this.mapEvent({
                onbeforesort:    target,
                onaftersort:    target,
                onbeforeadd:    target,
                onafteradd:        target,
                onbeforedelete:    target,
                onafterdelete:    target,
                ondataupdate:    target/*,
                onafterfilter:    target,
                onbeforefilter:    target*/
            });
        }

        var list = ["sort","add","remove","exists","getIdByIndex","getIndexById","getItem","updateItem","refresh","count","filter","find","getNextId","getPrevId","clearAll","getFirstId","getLastId","serialize","sync"];
        for (var i=0; i < list.length; i++)
            target[list[i]] = this._methodPush(this,list[i]);
    },
    addMark:function(id, mark, css, value, silent){
        var obj = this._marks[id]||{};
        this._marks[id] = obj;
        if (!obj[mark]){
            obj[mark] = value||true;
            if (css){
                var old_css = obj.$css||"";
                obj.$css = old_css+" "+mark;
            }
            if (!silent)
                this.refresh(id);
        }
        return obj[mark];
    },
    removeMark:function(id, mark, css, silent){
        var obj = this._marks[id];
        if (obj){
            if (obj[mark])
                delete obj[mark];
            if (css){
                var current_css = obj.$css;
                if (current_css){
                    obj.$css = current_css.replace(mark, "").replace("  "," ");
                }
            }
            if (!silent)
                this.refresh(id);
        }
    },
    getMark:function(id, mark){
        var obj = this._marks[id];
        return (obj?obj[mark]:false);
    },
    clearMark:function(name, css, silent){
        for (var id in this._marks){
            var obj = this._marks[id];
            if (obj[name]){
                delete obj[name];
                if (css && obj.$css)
                    obj.$css = obj.$css.replace(name, "").replace("  "," ");
                if (!silent)
                    this.refresh(id);
            }
        }
    },
    /*
        serializes data to a json object
    */
    serialize: function(all){
        var ids = this.order;
        if (all && this._filter_order)
            ids = this._filter_order;

        var result = [];
        for(var i=0; i< ids.length;i++) {
            var el = this.pull[ids[i]];
            if (this._scheme_serialize){
                el = this._scheme_serialize(el);
                if (el===false) continue;
            }
            result.push(el);
        }
        return result;
    },
    sorting:{
        create:function(config){
            return this._dir(config.dir, this._by(config.by, config.as));
        },
        as:{
            //handled by dataFeed
            "server":function(){
                return false;
            },
            "date":function(a,b){
                a=a-0; b=b-0;
                return a>b?1:(a<b?-1:0);
            },
            "int":function(a,b){
                a = a*1; b=b*1;
                return a>b?1:(a<b?-1:0);
            },
            "string_strict":function(a,b){
                a = a.toString(); b=b.toString();
                return a>b?1:(a<b?-1:0);
            },
            "string":function(a,b){
                if (!b) return 1;
                if (!a) return -1;

                a = a.toString().toLowerCase(); b=b.toString().toLowerCase();
                return a>b?1:(a<b?-1:0);
            }
        },
        _by:function(prop, method){
            if (!prop)
                return method;
            if (typeof method != "function")
                method = this.as[method||"string"];

            webix.assert(method, "Invalid sorting method");
            return function(a,b){
                return method(a[prop],b[prop]);
            };
        },
        _dir:function(prop, method){
            if (prop == "asc" || !prop)
                return method;
            return function(a,b){
                return method(a,b)*-1;
            };
        }
    }
};