Fetcher

The Fetcher is initialized during the app initialization and is attached to the app object. This class is designed to fetch data from an API on the client or server. It initializes the Model Store and Collection Store, and mixes in the Backbone.Events to allow you to trigger events on client or server the way you would in Backbone.

bootstrapData Fetcher.bootstrapData(modelMap)

Links the data from the App.bootstrapData to the corresponding store. This is how data from the initial server request is loaded into the client-side store.

fetch Fetcher.fetch(fetchSpec, [options], callback)

Fetches Models or Collections according to the parameters defined in the fetchSpec and populates the corresponding ModelStore and/or CollectionStore.

Example fetchSpec:

{
  user: {
    model: 'User',
    params: {id: 1},
    needsFetch: true,
    ensureKeys: ['id', 'name']
  },

  model: {
    model: 'Character',
    params: { name: 'Han Solo' }
  },

  starWarsCharacters: {
    collection: 'StarWarsCharacters',
    params: { film: 'Star Wars' }
  }
}

This fetchSpec will get two models (the User and Character models) and one collection (the StarWarsCharacters collection).

Extra options to pass to a fetchSpec:

• needsFetch - Allows you to force a fetch request
• ensureKeys - Ensures any stored data has all the required data, if not an API request will be made

The callback function will be called with an error and results from the fetch. For an example callback function, check out the Controller documentation.

options optional Allows you to set caching information. The defaults differ between client and server: by default API responses are not written or read from the cache on the server, but both are true on the client.

Example options:

var opts = {
  readFromCache: true,
  writeToCache: true
};

Fetcher.fetch(fetchSpec, opts, callback);

The fetch function will make an AJAX request if readFromCache is false or if the data does not exist in the ModelStore or CollectionStore. If the data isn't found in the relevant store, it makes AJAX requests for each item defined in the fetchSpec. Note: These AJAX requests are run in parallel.

fetchFromApi Fetcher.fetchFromApi(spec, options, callback)

Calls fetch for the model or collection with the given options and invokes the callback after the fetch is completed.

hydrate Fetcher.hydrate(summaries, [options], callback)

This method is called when attaching views to the DOM, specifically when attaching the child views. hydrate loops through each summary to retrieve the data from the corresponding Model Store or Collection Store for each child view, then it invokes the specified callback.

Hydration occurs either when the HTML has been loaded by the server, or when a view is creating an instance of a child view using a template adapter.

Arguments:

• summaries can be generated by the Fetcher.summarize function.
• options optional can be used to pass an instance of the app.
• callback this function is invoked after the data is retrieved from the store.

pendingFetches Fetcher.pendingFetches

A counter for the number of items currently being fetched. The fetch function keeps track of the number of pending fetches.

storeResults Fetcher.storeResults(results)

Saves each item from the results object into the corresponding store.

summarize Fetcher.summarize(modelOrCollection)

Returns a summary object of a collection or model. This is used when hydrating views, and passing data from the server to the client.

Example Model Summary:

{
  model: 'User',
  id: 1
}

Example Collection Summary:

  collection: 'Users',
  ids: [1, 2, 3],
  params: { id: [1, 2, 3] },
  meta: { page: 0 }