From 3b239349fa5cea650dbaa58befe7c453be70b2c8 Mon Sep 17 00:00:00 2001 From: jos Date: Fri, 2 May 2014 12:38:32 +0200 Subject: [PATCH] Extended DataSet documentation --- docs/dataset.html | 570 ++++++++++++++++++++++++++++------------------ src/DataSet.js | 8 +- 2 files changed, 354 insertions(+), 224 deletions(-) diff --git a/docs/dataset.html b/docs/dataset.html index 477d26a4..0828e37e 100644 --- a/docs/dataset.html +++ b/docs/dataset.html @@ -20,10 +20,10 @@
  • Overview
  • Example
  • Construction
    • -
  • Data Manipulation
    • -
  • Data Filtering
    • -
  • Data Formatting
    • +
  • Methods
  • Subscriptions
    • +
  • Data Manipulation
    • +
  • Data Selection
  • Data Policy
    • @@ -165,6 +165,294 @@ var data = new vis.DataSet([data] [, options]) +

    Methods

    + +

    DataSet contains the following methods.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    MethodReturn TypeDescription
    add(data [, senderId])Number[]Add data to the DataSet. Adding an item will fail when there already is an item with the same id. The function returns an array with the ids of the added items. See section Data Manipulation.
    clear([senderId])Number[]Clear all data from the DataSet. The function returns an array with the ids of the removed items.
    distinct(field)ArrayFind all distinct values of a specified field. Returns an unordered array containing all distinct values. If data items do not contain the specified field are ignored.
    forEach(callback [, options])none + Execute a callback function for every item in the dataset. + The available options are described in section Data Selection. +
    + get([options] [, data])
    + get(id [,options] [, data])
    + get(ids [, options] [, data]) +     		Object | Array | DataTable + Get a single item, multiple items, or all items from the DataSet. + Usage examples can be found in section Getting Data, and the available options are described in section Data Selection. If parameter data isprovided, items will be appended to this array or table, which is required in case of Google DataTable. +
    + getIds([options]) + Number[] + Get ids of all items or of a filtered set of items. + Available options are described in section Data Selection, except that options fields and convert are not applicable in case of getIds. +
    map(callback [, options])Array + Map every item in the DataSet. + The available options are described in section Data Selection. +
    max(field)Object | null + Find the item with maximum value of specified field. Returns null if no item is found. +
    min(field)Object | null + Find the item with minimum value of specified field. Returns null if no item is found. +
    off(event, callback)none + Unsubscribe from an event, remove an event listener. See section Subscriptions. +
    on(event, callback)none + Subscribe to an event, add an event listener. See section Subscriptions. +
    + remove(id [, senderId])
    + remove(ids [, senderId]) +     		Number[] + Remove on ore multiple items by id or by the items themselves. Returns an array with the ids of the removed items. See section Data Manipulation. +
    + update(id [, senderId])
    + update(ids [, senderId]) +     		Number[] + Update on ore existing items. When an item doesn't exist, it will be created. Returns an array with the ids of the removed items. See section Data Manipulation. +
    + + +

    Subscriptions

    + +

    + One can subscribe on changes in a DataSet. + A subscription can be created using the method on, + and removed with off. +

    + +
    +// create a DataSet
+var data = new vis.DataSet();
+
+// subscribe to any change in the DataSet
+data.on('*', function (event, properties, senderId) {
+  console.log('event:', event, 'properties:', properties, 'senderId:', senderId);
+});
+
+// add an item
+data.add({id: 1, text: 'item 1'});              // triggers an 'add' event
+data.update({id: 1, text: 'item 1 (updated)'}); // triggers an 'update' event
+data.remove(1);                                 // triggers an 'remove' event
+
    + + +

    On

    + +

    + Subscribe to an event. +

    + +Syntax: +
    DataSet.on(event, callback)
    + +Where: + + +

    Off

    + +

    + Unsubscribe from an event. +

    + +Syntax: +
    DataSet.off(event, callback)
    + +Where event and callback correspond with the +parameters used to subscribe to the event. + +

    Events

    + +

    + The following events are available for subscription: +

    + + + + + + + + + + + + + + + + + + + + + + +
    EventDescription
    add + The add event is triggered when an item + or a set of items is added, or when an item is updated while + not yet existing. +
    update + The update event is triggered when an existing item + or a set of existing items is updated. +
    remove + The remove event is triggered when an item + or a set of items is removed. +
    * + The * event is triggered when any of the events + add, update, and remove + occurs. +
    + +

    Callback

    + +

    + The callback functions of subscribers are called with the following + parameters: +

    + + 
    +function (event, properties, senderId) {
+  // handle the event
+});
+
    + +

    + where the parameters are defined as +

    + + + + + + + + + + + + + + + + + + + + + + +
    ParameterTypeDescription
    eventString + Any of the available events: add, + update, or remove. +
    propertiesObject | null + Optional properties providing more information on the event. + In case of the events add, + update, and remove, + properties is always an object containing a property + items, which contains an array with the ids of the affected + items. +
    senderIdString | Number + An senderId, optionally provided by the application code + which triggered the event. If senderId is not provided, the + argument will be null. +
    + +

    Data Manipulation

    @@ -322,70 +610,18 @@ Syntax:

    -

    Data Filtering

    - -

    - Data can be retrieved from the DataSet using the method get. - This method can return a single item or a list with items. -

    - -

    A single item can be retrieved by its id:

    - -
    -var item1 = dataset.get(1);
-
    - -

    A selection of items can be retrieved by providing an array with ids:

    - -
    -var items = dataset.get([1, 3, 4]); // retrieve items 1, 3, and 4
-
    - -

    All items can be retrieved by simply calling get without - specifying an id:

    - -
    -var items = dataset.get();          // retrieve all items
-
    - -

    - Items can be filtered on specific properties by providing a filter - function. A filter function is executed for each of the items in the - DataSet, and is called with the item as parameter. The function must - return a boolean. All items for which the filter function returns - true will be emitted. -

    - -
    -// retrieve all items having a property group with value 2
-var group2 = dataset.get({
-  filter: function (item) {
-    return (item.group == 2);
-  }
-});
-
-// retrieve all items having a property balance with a value above zero
-var positiveBalance = dataset.get({
-  filter: function (item) {
-    return (item.balance > 0);
-  }
-});
-
-
    - - -

    Data Formatting

    +

    Data Selection

    - The DataSet contains functionality to format data retrieved via the - method get. The method get has the following - syntax: + The DataSet contains functionality to format, filter, and sort data retrieved via the + methods get, getIds, forEach, and map. These methods have the following syntax: 

    -var item  = DataSet.get(id, options);   // retrieve a single item
-var items = DataSet.get(ids, options);  // retrieve a selection of items
-var items = DataSet.get(options);       // retrieve all items or a filtered set
+DataSet.get([id] [, options] [, data]);
+DataSet.getIds([options]);
+DataSet.forEach(callback [, options]);
+DataSet.map(callback [, options]);

    @@ -471,6 +707,59 @@ var items = data.get({ }); +

    Getting Data

    + +

    + Data can be retrieved from the DataSet using the method get. + This method can return a single item or a list with items. +

    + +

    A single item can be retrieved by its id:

    + +
    +var item1 = dataset.get(1);
+
    + +

    A selection of items can be retrieved by providing an array with ids:

    + +
    +var items = dataset.get([1, 3, 4]); // retrieve items 1, 3, and 4
+
    + +

    All items can be retrieved by simply calling get without + specifying an id:

    + +
    +var items = dataset.get();          // retrieve all items
+
    + + +

    Data Filtering

    + +

    + Items can be filtered on specific properties by providing a filter + function. A filter function is executed for each of the items in the + DataSet, and is called with the item as parameter. The function must + return a boolean. All items for which the filter function returns + true will be emitted. +

    + +
    +// retrieve all items having a property group with value 2
+var group2 = dataset.get({
+  filter: function (item) {
+    return (item.group == 2);
+  }
+});
+
+// retrieve all items having a property balance with a value above zero
+var positiveBalance = dataset.get({
+  filter: function (item) {
+    return (item.balance > 0);
+  }
+});
+
+

    Data Types

    @@ -546,163 +835,6 @@ var items = data.get({ -

    Subscriptions

    - -

    - One can subscribe on changes in a DataSet. - A subscription can be created using the method on, - and removed with off. -

    - -
    -// create a DataSet
-var data = new vis.DataSet();
-
-// subscribe to any change in the DataSet
-data.on('*', function (event, properties, senderId) {
-  console.log('event:', event, 'properties:', properties, 'senderId:', senderId);
-});
-
-// add an item
-data.add({id: 1, text: 'item 1'});              // triggers an 'add' event
-data.update({id: 1, text: 'item 1 (updated)'}); // triggers an 'update' event
-data.remove(1);                                 // triggers an 'remove' event
-
    - - -

    On

    - -

    - Subscribe to an event. -

    - -Syntax: -
    DataSet.on(event, callback)
    - -Where: - - -

    Off

    - -

    - Unsubscribe from an event. -

    - -Syntax: -
    DataSet.off(event, callback)
    - -Where event and callback correspond with the -parameters used to subscribe to the event. - -

    Events

    - -

    - The following events are available for subscription: -

    - - - - - - - - - - - - - - - - - - - - - - -
    EventDescription
    add - The add event is triggered when an item - or a set of items is added, or when an item is updated while - not yet existing. -
    update - The update event is triggered when an existing item - or a set of existing items is updated. -
    remove - The remove event is triggered when an item - or a set of items is removed. -
    * - The * event is triggered when any of the events - add, update, and remove - occurs. -
    - -

    Callback

    - -

    - The callback functions of subscribers are called with the following - parameters: -

    - - 
    -function (event, properties, senderId) {
-  // handle the event
-});
-
    - -

    - where the parameters are defined as -

    - - - - - - - - - - - - - - - - - - - - - - -
    ParameterTypeDescription
    eventString - Any of the available events: add, - update, or remove. -
    propertiesObject | null - Optional properties providing more information on the event. - In case of the events add, - update, and remove, - properties is always an object containing a property - items, which contains an array with the ids of the affected - items. -
    senderIdString | Number - An senderId, optionally provided by the application code - which triggered the event. If senderId is not provided, the - argument will be null. -
    - - -

    Data Policy

    All code and data is processed and rendered in the browser. diff --git a/src/DataSet.js b/src/DataSet.js index a7b95d04..ca93ade1 100644 --- a/src/DataSet.js +++ b/src/DataSet.js @@ -521,7 +521,6 @@ DataSet.prototype.getIds = function (options) { /** * Execute a callback function for every item in the dataset. - * The order of the items is not determined. * @param {function} callback * @param {Object} [options] Available options: * {Object.} [convert] @@ -767,9 +766,8 @@ DataSet.prototype.min = function (field) { /** * Find all distinct values of a specified field * @param {String} field - * @return {Array} values Array containing all distinct values. If the data - * items do not contain the specified field, an array - * containing a single value undefined is returned. + * @return {Array} values Array containing all distinct values. If data items + * do not contain the specified field are ignored. * The returned array is unordered. */ DataSet.prototype.distinct = function (field) { @@ -789,7 +787,7 @@ DataSet.prototype.distinct = function (field) { break; } } - if (!exists) { + if (!exists && (value !== undefined)) { values[count] = value; count++; }