datastore

a set of datastore methods

object datastore;

Details

This is an experimental API that might be changed in the future.

Note, that Tasks and Links should be modified using the common API of Gantt. Modifying tasks or links directly in the datastore can produce unexpected results. Datastores are expected to be used for resources or other custom objects.

A new datastore can be created using createDatastore method.
The datastore object possesses the following methods and events:

Methods

parse (data): void - loads data from an array
- data - (Array<object>) - the data to load

gantt.$resourcesStore.parse([
    {id: 1, text: "QA", parent:null},
    {id: 2, text: "Development", parent:null},
    {id: 3, text: "Sales", parent:null},
    {id: 4, text: "Other", parent:null},
    {id: 5, text: "Unassigned", parent:4},
    {id: 6, text: "John", parent:1},
    {id: 7, text: "Mike", parent:2},
    {id: 8, text: "Anna", parent:2},
    {id: 9, text: "Bill", parent:3},
    {id: 10, text: "Floe", parent:3}
]);

Related sample: Resource load diagram

The twin of datastore.parse() is gantt.parse().

Calls the onBeforeParse, onItemLoading, onParse, and onStoreUpdated events.

getItem (id): object | void - returns the item by its id
- id - (string | number) - the id of the item

var store = gantt.getDatastore(gantt.config.resource_store);
var resource = store.getItem(resourceId);

Related sample: Resource load diagram

The twins of datastore.getItem() are gantt.getTask() and gantt.getLink().

updateItem (id, item): void - updates the specified item
- id - (string | number) - the id of the item
- item? - (object) - an object the item

var store = gantt.getDatastore(gantt.config.resource_store);
var resource = store.getItem(resourceId);
resource.text = "modified";
store.updateItem(resourceId);
// or
store.updateItem(resourceId, { text: "modified" });

The twins of datastore.updateItem() are gantt.updateTask() and gantt.updateLink().

Calls the onBeforeUpdate, onAfterUpdate and onStoreUpdated events.

removeItem (id): void - deletes the specified item
- id - (string | number) - the id of the item

var store = gantt.getDatastore(gantt.config.resource_store);
store.removeItem(resourceId);

The twins of datastore.removeItem() are gantt.deleteTask() and gantt.deleteLink().

Calls the onBeforeDelete, onAfterDelete and onStoreUpdated events.

isVisible (id): boolean - checks whether the specified item is visible or hidden via filters
- id - (string | number) - the id of the item
Returns true, if the task is visible. Otherwise, false.

var store = gantt.getDatastore(gantt.config.resource_store);
if(store.isVisible(resourceId)){
    console.log(resourceId);
}

The twin of datastore.isVisible() is gantt.isTaskVisible().

getVisibleItems (): Array<object> - returns the array of visible items

var store = gantt.getDatastore(gantt.config.resource_store);
var items = store.getVisibleItems();

addItem (item, index): number | string - adds a new item to the datastore
- item - (object) - the item object
- index? - (number) - the position the task will be added into (0 or greater)
Returns the id of the item.

var store = gantt.getDatastore(gantt.config.resource_store);
var itemId = store.addItem({
    text: "Unassigned",
    parent:4
});

The twins of datastore.addItem() are gantt.addTask() and gantt.addLink().

Calls the onBeforeAdd, onAfterAdd and onStoreUpdated events.

changeId (oldId, newId): void - changes the id of the item
- oldId - (string | number) - the current item's id
- newId - (string | number) - the new item's id

var store = gantt.getDatastore(gantt.config.resource_store);
 
var itemId = store.addItem({
    text: "Unassigned",
    parent:4
});
 
// itemId - temporary client-side id of the new item
// once item is saved to the database - update the client with the new id:
 
store.changeId(itemId, "databaseId");

The twins of datastore.changeId() are gantt.changeTaskId() and gantt.changeLinkId().

Calls the onIdChange event.

exists (id): boolean - checks whether the specified item exists in the datastore
- id - (string | number) - the item's id
Returns true, if the task exists. Otherwise, false.

var store = gantt.getDatastore(gantt.config.resource_store);
 
if(store.exists(resourceId)){
    console.log(resourceId);
}

The twins of datastore.exists() are gantt.isTaskExists() and gantt.isLinkExists().

move (sindex, tindex): void - moves an item to a new position
- sindex - (number) - the index of the current position of the task
- tindex - (number) - the index of the position that the item will be moved to

var store = gantt.getDatastore(gantt.config.resource_store);
 
// swap two items
var idA = 1;
var idB = 5;
var indexA = store.getIndexById(idA);
var indexB = store.getIndexById(idB);
store.move(indexB, indexA);
 
indexA = store.getIndexById(idA);
store.move(indexA, indexB);

The twin of datastore.move() is gantt.moveTask().

Call the onStoreUpdated event.

clearAll (): void - clears the datastore

var store = gantt.getDatastore(gantt.config.resource_store);
store.clearAll();

The twin of datastore.clearAll() is gantt.clearAll().

Calls the onClearAll, onBeforeStoreUpdate and onStoreUpdated events.

silent (callback): void - execute the code without firing API events of the datastore
- callback - (Function) - the callback function

var store = gantt.getDatastore(gantt.config.resource_store);
store.silent(function(){
    store.eachItem(function(item){
        item.text += " modified";
        store.updateItem(item.id);
    });
});
store.refresh();

The twin of datastore.silent() is gantt.silent().

refresh (id): void - fires repainting of events of the specified record, runs filters
- id? - (string | number) - optional, the id of the record

var store = gantt.getDatastore(gantt.config.resource_store);
store.refresh(itemId); // repaints an item
store.refresh(); // repaints all items

The twins of datastore.refresh() are gantt.refreshTask() and gantt.refreshLink().

Calls the onBeforeStoreUpdate, onBeforeFilter, onFilterItem, onFilter and onStoreUpdated events.

count (): number - returns the number of items that are currently loaded into the datastore

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onParse", function(){
    alert(store.count() + " items loaded");
});

The twins of datastore.count() are gantt.getTaskCount() and gantt.getLinkCount().

countVisible (): number - returns the number of items that are currently visible

var store = gantt.getDatastore(gantt.config.resource_store);
alert(store.countVisible() + " items are visible");

The twin of datastore.countVisible() is gantt.getVisibleTaskCount().

eachItem (callback): void - iterates over all tasks of the datastore
- callback - (Function) - the callback function

var store = gantt.getDatastore(gantt.config.resource_store);
 
var searchItems = [];
store.eachItem(function(item){
    if(!item.value){
        searchItems.push(item);
    }
});

The twin of datastore.eachItem() is gantt.eachTask().

filter (): void - runs the filters and updates visible array of items

store.refresh()

var store = gantt.getDatastore(gantt.config.resource_store);
store.filter();

sort (field, desc, parent, silent): void - sorts items in the resource grid
- field - (string | Function) - the name of the column that the resource grid will be sorted by or a custom sorting function
- desc? - (boolean) - specifies the sorting direction: true - descending sort and false - ascending sort. By default, false
- parent? - (string | number) - the id of the parent item. Specify the parameter if you want to sort items only in the branch of the specified parent.
- silent? - (boolean) - specifies whether rendering should be invoked after reordering items

var store = gantt.getDatastore(gantt.config.resource_store);
store.parse([
    {id: 1, text: "QA", parent:null},
    {id: 2, text: "Development", parent:null},
    {id: 3, text: "Sales", parent:null},
    {id: 4, text: "Other", parent:null},
    {id: 5, text: "Unassigned", parent:4},
    {id: 6, text: "John", parent:1},
    {id: 7, text: "Mike", parent:2},
    {id: 8, text: "Anna", parent:2},
    {id: 9, text: "Bill", parent:3},
    {id: 10, text: "Floe", parent:3}
]);
 
// sort the resource grid by the column
var resourceSortDirection = false;
function sortResources(){
    resourceSortDirection = !resourceSortDirection;
    gantt.getDatastore("resource").sort("text", resourceSortDirection)
    gantt.render();
}

var resourceSortDirection = false;
function sortResources(){
    resourceSortDirection = !resourceSortDirection;
    gantt.getDatastore("resource").sort(function (resource1, resource2){
        return resource1.id - resource2.id;
    }, resourceSortDirection)
    gantt.render();
}

The twin of datastore.sort() is gantt.sort().

getIndexRange (from, to): Array<object> - returns records between the specified indexes
- from - (number) - the position of the start record
- to - (number) - the position of the end record

var store = gantt.getDatastore(gantt.config.resource_store);
var itemsInViewPort = store.getIndexRange(5, 10);// get items from 5th to 10th

getItems (): Array<object> - returns all records of the datastore

var store = gantt.getDatastore(gantt.config.resource_store);
var items = store.getItems();

The twins of datastore.getItems() are gantt.getTaskByTime() and gantt.getLinks().

getIdByIndex (index): string | number | void - returns the id of the item by its index. Returns `undefined` if there is no item at the specified index.
- index - (number) - the position of the item

var store = gantt.getDatastore(gantt.config.resource_store);
var firstItem = store.getIdByIndex(0);

The twin of datastore.getIdByIndex() is gantt.getTaskByIndex().

getIndexById (id): number - returns the index of the item by its id. Returns `-1` if no such item exists in the datastore.
- id - (string | number) - the id of the item

var store = gantt.getDatastore(gantt.config.resource_store);
var itemIndex = store.getIndexById(5);

The twin of datastore.getIndexById() is gantt.getTaskIndex().

getFirst (): string | number | null - returns the id of the first item of the datastore

var store = gantt.getDatastore(gantt.config.resource_store);
var firstId = store.getFirst();

getLast (): string | number | null - returns the id of the last item of the datastore

var store = gantt.getDatastore(gantt.config.resource_store);
var lastId = store.getLast();

getNext (id): string | number | null - returns the id of the next item of the datastore
- id - (string | number) - the item's id

var store = gantt.getDatastore(gantt.config.resource_store);
var firstId = store.getFirst();
var secondId = store.getNext(firstId);

The twin of datastore.getNext() is gantt.getNext().

getPrev (id): string | number | null - returns the id of the previous item of the datastore
- id - (string | number) - the item's id

var store = gantt.getDatastore(gantt.config.resource_store);
var prevId = store.getPrev(itemId);

The twin of datastore.getPrev() is gantt.getPrev().

destructor (): void - clears the datastore and removes all attached event handlers. The datastore is not usable after this method is called.

var store = gantt.getDatastore(gantt.config.resource_store);
store.destructor();

The twin of datastore.destructor() is gantt.destructor().

attachEvent (name, handler, settings): string - attaches the handler to an inner event of DataStore
- name - (string) - the event's name, case-insensitive
- handler - (Function) - the handler function
- settings? - (object) - optional, an object with settings for the event handler

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onAfterSelect", function(id){
    gantt.refreshData();
});

The twin of datastore.attachEvent() is gantt.attachEvent().

callEvent (name, params): boolean - calls an inner event
- name - (string) - the event's name, case-insensitive
- params - (Array<any>) - an array of the event-related data

var store = gantt.getDatastore(gantt.config.resource_store);
store.callEvent("CustomEvent", [param1, param2]);

The twin of datastore.callEvent() is gantt.callEvent().

detachEvent (id): void - detaches a handler from an event (which was attached before by the attachEvent() method)
- id - (string) - the event's id

var store = gantt.getDatastore(gantt.config.resource_store);
var handlerId = store.attachEvent("onAfterSelect", function(id){
    gantt.refreshData();
});
 
// detach a listener
store.detachEvent(handlerId);

The twin of datastore.detachEvent() is gantt.detachEvent().

Events

onItemLoading (item) - fires when an item is being loaded from the data source
- item - (object) - the object of an item
Return false to prevent the default action of the event, otherwise true.

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onItemLoading", function(item){
    if(item.valid){ // filter items on loading by custom property
        return true;
    }
    return false;
});

The twin of the onItemLoading event of datastore is the onTaskLoading event of Gantt.

onBeforeParse (data) - fires before data started to be parsed
- data - (Array <any>) - the array with the data that was loaded

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeParse", function(item){
    console.time("StoreParse");
});
store.attachEvent("onParse", function(item){
    console.timeEnd("StoreParse");
});

The twin of the onBeforeParse event of datastore is the onBeforeParse event of Gantt.

onParse (data) - fires after data were parsed (became available for API) but before they were rendered in the Gantt chart
- data - (Array <any>) - the array with the data that was loaded

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeParse", function(item){
    console.time("StoreParse");
});
store.attachEvent("onParse", function(item){
    console.timeEnd("StoreParse");
});

The twin of the onParse event of datastore is the onParse event of Gantt.

onBeforeUpdate (id, item) - fires before an item is updated
- id - (string | number) - the id of an item
- item - (object) - the new (updated) object of the item
Return false to prevent the default action of the event, otherwise true.

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeUpdate", function(id, item){
    // your code here
    return true;
});

The twins of the onBeforeUpdate event of datastore are the onBeforeTaskUpdate and onBeforeLinkUpdate events of Gantt.

onAfterUpdate (id, item) - fires after an item is updated
- id - (string | number) - the id of an item
- item - (object) - the object of the item

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onAfterUpdate", function(id, item){
    // your code here
});

The twins of the onAfterUpdate event of datastore are the onAfterTaskUpdate and onAfterLinkUpdate events of Gantt.

onBeforeDelete (id, item) - fires before an item is deleted
- id - (string | number) - the id of an item
- item - (object) - the object of the item
Return false to prevent the default action of the event, otherwise true.

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeDelete", function(id, item){
    // your code here
    return true;
});

The twins of the onBeforeDelete event of datastore are the onBeforeTaskDelete and onBeforeLinkDelete events of Gantt.

onAfterDelete (id, item) - fires after an item is deleted
- id - (string | number) - the id of an item
- item - (object) - the object of the item

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onAfterDelete", function(id, item){
    // your code here
});

The twins of the onAfterDelete event of datastore are the onAfterTaskDelete and onAfterLinkDelete events of Gantt.

onBeforeAdd (id, item) - fires before a new item is added to the datastore
- id - (string | number) - the id of an item
- item - (object) - the object of the item
Return false to prevent the default action of the event, otherwise true.

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeAdd", function(id, item){
    // your code here
    return true;
});

The twins of the onBeforeAdd event of datastore are the onBeforeTaskAdd and onBeforeLinkAdd events of Gantt.

onAfterAdd (id, item) - fires after an item is added to the datastore
- id - (string | number) - the id of an item
- item - (object) - the object of the item

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onAfterAdd", function(id, item){
    // your code here
});

The twins of the onAfterAdd event of datastore are the onAfterTaskAdd and onAfterLinkAdd events of Gantt.

onIdChange (id, newId) - fires when the id of an item is changed
- id - (string | number) - the id of an item
- newId - (string | number) - the new id of the item

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onIdChange", function(oldId, newId){
    // your code here
});

The twin of the onIdChange event of datastore is the onTaskIdChange event of Gantt.

onClearAll () - fires after all items were removed from the datastore

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onClearAll", function(){
    // your code here
});

The twin of the onClearAll event of datastore is the onClear event of Gantt.

onBeforeStoreUpdate (id, item, action) - fires before the datastore is refreshed
- id - (string | number | null) - the id of an item or null
- item - (object | null) - the item object or null
- action - (string | null) - the action type ("paint", "move", "add", "delete", null)
Return false to prevent the default action of the event, otherwise true.
This event signals that the datastore items need a repaint. `null` argument value means that the whole datastore is updated.

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeStoreUpdate", function(id, item, action){
    // your code here
    return true;
});

onStoreUpdated (id, item, action) - fires after the datastore has been refreshed
- id - (string | number | null) - the id of an item or null
- item - (object | null) - the item object or null
- action - (string | null) - the action type ("paint", "move", "add", "delete", null)
This event signals that the datastore items need a repaint. `null` argument value means that the whole datastore is updated.

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onStoreUpdated", function(id, item, action){
    // your code here
});

onBeforeFilter () - fires before filtering is applied

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeFilter", function(){
    console.time("filtering");
});
store.attachEvent("onFilter", function(){
    console.timeEnd("filtering");
});

onFilter () - fires after the datastore has update the filtering state

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onBeforeFilter", function(){
    console.time("filtering");
});
store.attachEvent("onFilter", function(){
    console.timeEnd("filtering");
});

onFilterItem (id, item) - fires for each item during the filtering stage, returning `false` will mark item as not visible
- id - (string | number) - the id of an item
- item - (object) - the item object
Return false to prevent the default action of the event, otherwise true.

var store = gantt.getDatastore(gantt.config.resource_store);
store.attachEvent("onFilterItem", function(id, item){
    // your code here
    return true;
});

The twin of the onFilterItem event of datastore is the onBeforeTaskDisplay event of Gantt.

onDestroy () - fires after the destructor() method of the datastore is called

var datastore = gantt.createDatastore({
    name: gantt.config.resource_store,
    type: "treeDatastore",
    initItem: function (item) {
        item.parent = item.parent || gantt.config.root_id;
        item[gantt.config.resource_property] = item.parent;
        item.open = true;
        return item;
    }
});
 
datastore.attachEvent("onDestroy", function(){
    alert("free custom resources");
});
 
datastore.destructor();