delite/Store
delite/Store
is a mixin that can be mixed into a class inheriting from delite/Widget
or decor/Evented
in order to query a store object from the dstore project and create render items for this
widget based on the store items.
This is particularly useful for a widget that needs to create items (or render items) based on store entries (like a data list, grid or calendar schedule etc...). Using this mixin the widget will benefit from a standard API and way of doing things.
The store is queried each time one of the following properties is set on the instance:
- store: references a
dstore/api/Store
implementation - query: a query object to be passed to the store
filter()
function
When the store is queried, render items are created using the itemToRenderItem()
function which by default just returns the
store item. Render items are typically used in widgets rendering several "data items" (arbitrary number of items
connected to data) to specify how those "data items" have to be rendered. This means the render items are used as input
for the various "data items" rendered in the widget. Depending on the targeted widget, render items expect several
properties to be present like a label, an icon etc. Classes using the mixin might override itemToRenderItem()
to create
their own render items.
For example the store item (typically coming from a data server) might contain:
{
lastName: "Smith"
firstName: "John",
department: "marketing",
title: "head of department",
jobDescription: "in charge of defining the marketing strategy for the company"
}
while the widget render item requires and contains exactly what the widget needs to consume, in this case for example:
{
name: "John Smith"
jobtitle: "head of department"
}
The itemToRenderItem()
function is in charge of doing that transformation. Alternatively one can use the
delite/StoreMap
mixin which adds mapping functionality to the store mixin and automatically creates the
render items using this mapping.
Once created the render items array is passed into the initItems()
function and by default store in the
renderItems
property.
In addition to this, if the store is an observable store (dstore/Trackable
) the changes to the data in the store will
be tracked and the following functions will be called on each type of modification:
itemRemoved
if an item has been removeditemAdded
if an item has been addeditemUpdated
if an item has been updated (its properties have changed)itemMoved
if an item has been moved in an ordered store.
By default those functions update the renderItems
accordingly.
Classes extending the mixin have two ways of leveraging the work of delite/Store
. They can either listen to the changes
to the renderItems
property or redefine the various functions of the mixin to be notified of changes made to the render
items.
Listening to changes of renderItems
is best done via the refreshRendering()
method:
define(["delite/register", "delite/Widget", "delite/Store"/*, ...*/],
function (register, Widget, Store/*, ...*/) {
return register("employees-list", [HTMElement, Widget, Store], {
itemToRenderItem: function (item) {
return {
name: item.firstName + " " + item.lastName,
jobtitle: item.title
}
},
refreshRendering: function (props) {
if ("renderItem" in props) {
// render item has changed, do something to reflect that in the rendering by adding for example
// a DOM element per item using the properties on the render item
}
}
});
});