Merge pull request #116 from teamsnap/smart-load

Smart load

Author: matthopson

CHANGELOG.md

@@ -1,5 +1,10 @@
 # TeamSnap JavaScript SDK CHANGELOG
 
+### Feb 15, 2016 // Version 1.9.0
+- Refactors `bulkLoad` to accept "Smart Load" params.
+
+---
+
 ### Feb 4, 2016 // Version 1.8.1
 - Update `canEditItem()` helper to return false when a manager attempts to edit an owner's member item.
 

docs/collections/teams.md

@@ -146,21 +146,44 @@ teamsnap.saveTeam(team).then(function(){
 
 
 <a id="bulkLoad"></a>
-## `bulkLoad(teamId, types, callback)`
+## `bulkLoad(teamId, types, callback)` / `bulkLoad(params, callback)`
 Query that returns multiple types based on provided parameters.
 
+In addition to bulk loading specific types for a given team, you can scope and filter the query to
+return more specific datasets. We sometimes refer to this as "Smart Load", but it's still APIv3's
+`bulk_load` query.
+
 _Note: Some items, such as `availability` are not currently available for `bulkLoad` for performance reasons. Likewise, loading many types at once without narrowing the scope may provide a less than optimal response, or possibly incur an API timeout with larger datasets._
 
 ### Params
+_Note: There are two ways you can call `bulkLoad`. This is the simple / classic way._
 * `teamId`: [int] - a `teamId` to load items for.
 * `types`: [array] - array of types to load.
 * `callback`: [function] - callback to be executed when the operation completes.
 
+_Using "Smart Load" params_
+* `params`: [object] - object should contain the following params:
+  - `teamId`: [int] - a `teamId` to load items for.
+  - `types`: [array] - array of types to load.
+  - `scopeTo`: [string] - item in the query to scope other items to.
+  - `[itemType__queryParam]`: [string] - additional filters can be set with the item's type and one of its available search params separated by a double underscore (`__`). This accepts a string for the value - which could be a date, an ID, or event a list of IDs. See the specific event's available search params with `teamsnap.collections.[itemCollection].queries.search.params` where `itemCollection` is the collection to look up.
+* `callback`: [function] - callback to be executed when the operation completes.
+
 ### Examples
 ```javascript
 // ~~~~~
 // Bulk loads several types at once.
-teamsnap.bulkLoad(1, ['member', 'event', 'availability']);
+teamsnap.bulkLoad(1, ['member', 'event', 'assignment']);
+
+// ~~~~~
+// Bulk load events and assignments related to eventId 1-6.
+bulkLoadParams = {
+  teamId: 1,
+  types: ['event', 'assignment'],
+  scopeTo: 'event',
+  event__id: '1,2,3,4,5,6'
+}
+teamsnap.bulkLoad(bulkLoadParams);
 ```
 
 

lib/teamsnap.js

@@ -2768,13 +2768,22 @@ exports.deleteTeam = function(team, callback) {
 };
 
 exports.bulkLoad = function(teamId, types, callback) {
-  var params;
-  if (!this.isId(teamId)) {
-    throw new TSArgsError('teamsnap.bulkLoad', 'teamId must be provided');
-  }
-  if (typeof types === 'function') {
-    callback = types;
-    types = null;
+  var loadParams, params;
+  if (typeof teamId === 'object') {
+    loadParams = teamId;
+    if (!this.isId(loadParams.teamId)) {
+      throw new TSArgsError('teamsnap.bulkLoad', 'teamId must be provided');
+    }
+    teamId = loadParams.teamId;
+    types = loadParams.types;
+  } else {
+    if (!this.isId(teamId)) {
+      throw new TSArgsError('teamsnap.bulkLoad', 'teamId must be provided');
+    }
+    if (typeof types === 'function') {
+      callback = types;
+      types = null;
+    }
   }
   if (!Array.isArray(types)) {
     types = this.getTeamTypes();
@@ -2784,6 +2793,9 @@ exports.bulkLoad = function(teamId, types, callback) {
     teamId: teamId,
     types: types.map(this.underscoreType).join(',')
   };
+  if ((loadParams != null ? loadParams.scopeTo : void 0) != null) {
+    params.scopeTo = this.underscoreType(loadParams.scopeTo);
+  }
   return this.collections.root.queryItems('bulkLoad', params, callback);
 };
 
@@ -3854,7 +3866,7 @@ MetaList = (function() {
   };
 
   MetaList.prototype._request = function(request, method, rel, params, type) {
-    var data, entry, key, value;
+    var data, entry, filteredOn, itemCollection, key, value;
     if (!(entry = this[rel])) {
       throw new TSError("Unable to find rel '" + rel + "'");
     }
@@ -3874,6 +3886,12 @@ MetaList = (function() {
         }
         if (entry.params.hasOwnProperty(key)) {
           data[underscore(key)] = value;
+        } else if (key.indexOf('__') !== -1) {
+          filteredOn = key.split('__');
+          itemCollection = teamsnap.getCollectionForItem(filteredOn[0]);
+          if (itemCollection.queries.search.params.hasOwnProperty(filteredOn[1])) {
+            data[underscore(key)] = value;
+          }
         }
       }
     }
@@ -5769,7 +5787,7 @@ ref = require('./model'), Collection = ref.Collection, Item = ref.Item;
 require('./errors');
 
 TeamSnap = (function() {
-  TeamSnap.prototype.version = '1.8.1';
+  TeamSnap.prototype.version = '1.9.0';
 
   TeamSnap.prototype.promises = promises;
 

lib/teamsnap.min.js

@@ -1,6 +1,6 @@
 {
   "name": "teamsnap.js",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "A JavaScript library for using the TeamSnap API.",
   "author": "Jacob Wright with TeamSnap (http://www.teamsnap.com)",
   "homepage": "https://github.com/teamsnap/teamsnap-javascript-sdk",

package.json

@@ -46,18 +46,29 @@ exports.deleteTeam = (team, callback) ->
 
 # Loads all items associated with a team, optionally limited by the types array
 exports.bulkLoad = (teamId, types, callback) ->
-  unless @isId teamId
-    throw new TSArgsError 'teamsnap.bulkLoad', 'teamId must be provided'
+  if typeof teamId is 'object'
+    loadParams = teamId
+    # Using params object (smartload)
+    unless @isId loadParams.teamId
+      throw new TSArgsError 'teamsnap.bulkLoad', 'teamId must be provided'
+    teamId = loadParams.teamId
+    types = loadParams.types
+  else
+    # Using classic bulk_load
+    unless @isId teamId
+      throw new TSArgsError 'teamsnap.bulkLoad', 'teamId must be provided'
 
-  if typeof types is 'function'
-    callback = types
-    types = null
+    if typeof types is 'function'
+      callback = types
+      types = null
 
   unless Array.isArray types
     types = @getTeamTypes()
     types.splice types.indexOf('availability'), 1
 
   params = teamId: teamId, types: types.map(@underscoreType).join(',')
+  if loadParams?.scopeTo?
+    params.scopeTo = @underscoreType(loadParams.scopeTo)
   @collections.root.queryItems 'bulkLoad', params, callback
 
 

src/collections/teams.coffee

@@ -302,6 +302,13 @@ class MetaList
 
         if entry.params.hasOwnProperty(key)
           data[underscore key] = value
+        # Check for search filters (example: `event__id`)
+        else if key.indexOf('__') isnt -1
+          filteredOn = key.split '__'
+          itemCollection = teamsnap.getCollectionForItem(filteredOn[0])
+          # Ensure valid param on filtered item type's search query
+          if itemCollection.queries.search.params.hasOwnProperty filteredOn[1]
+            data[underscore(key)] = value
 
     request(method, entry.href, data).then (xhr) ->
       items = if xhr.data?.collection?.items

src/model.coffee

@@ -3,7 +3,7 @@ promises = require './promises'
 require './errors'
 
 class TeamSnap
-  version: '1.8.1'
+  version: '1.9.0'
   promises: promises
   when: promises.when
   TeamSnap: TeamSnap