This is the central component of Tableling, a subclass of Backbone.Marionette.Layout. It provides no view and only handles two things:

• Fetching data from a Backbone.Collection
• Managing events with a Backbone.Marionette.EventAggregator

The table configuration is composed of 4 attributes:

• pageSize - the number of records per page
• page - the current page (starts at 1)
• quickSearch - a text that records should match
• sort - columns and directions that records should be sorted by

To refresh table rows, the table performs a fetch on its Backbone.Collection. This collection must be returned by getCollection which is not implemented here, meaning that subclasses must override it. Tableling.Modular provides an implementation.

When the table calls the fetch method of Backbone.Collection, it passes the current table configuration as the data option. With the default Backbone sync, they are sent as parameters to the jQuery ajax request sent to the backend. This is an example of fetch options:

{
  "data" : {
    "pageSize" : 15,
    "page" : 2,
    "quickSearch" : "tale"
  }
}

If you have additional options to pass to fetch, you can set fetchOptions when extending or when instantiating.

var CustomTable = Tableling.Table.extend({
  fetchOptions : {
    type : 'POST' // Fetch with POST.
  }
});

new CustomTable({
  fetchOptions : {
    type : 'GET' // Fetch with GET (this instance only).
  }
});

This is an example of fetch options using the custom table above:

{
  "type" : "POST",
  "data" : {
    "pageSize" : 15,
    "page" : 1,
    "type" : "POST"
  }
}

Tableling.Table expects the response from a fetch to have a total property containing the total number of records (not just in the current page).

This means that the classic Backbone.Collection format (array of objects) does not work. This kind of format is expected instead:

{
  "total": 12,
  "data": [
    { /* record data */ },
    { /* record data */ }
  ]
}

You can use a Tableling.Collection which will automatically extract models from the data property, or you can roll your own by overriding parse.

The table is event-driven with a Backbone.Marionette.EventAggregator. A new aggregator is automatically created when the table is instantiated, or you can pass your own with the vent option.

var myVent = new Backbone.Marionette.EventAggregator();

new Tableling.Plain.Table({
  vent : myVent
});

Triggered after the table is rendered. The initial table configuration is passed as argument.

This is typically used by modules (e.g. page size select box) to update their state when first rendered.

var CustomPageSizeView = Backbone.Marionette.ItemView.extend({

  template : _.template('<input type="text" name="pageSize" value="15" />'),

  ui : {
    field : '[name="pageSize"]'
  },

  initialize : function(vent) {
    vent.on('table:setup', this.refresh, this);
  },

  refresh : function(config) {
    this.ui.field.val(config.pageSize);
  }
});

Triggered to update the table configuration (e.g. change page size). New values of table configuration attributes are passed as argument. Used by modules to refresh the table on changes.

// Change to page 2 with 10 records per page.
table.vent.trigger('table:update', { pageSize: 10, page: 2 });

Triggered when the table is fetching data from the collection. The current table configuration is passed as argument.

table.vent.on('table:refreshing', function(config) {
  console.log('debug: table is fetching page ' + config.page + ' (page size ' + config.pageSize + ')');
});

Triggered when the table is done fetching. The current table configuration with collection meta data (length and total) are passed as argument.

table.vent.on('table:refreshed', function(config) {
  console.log('debug: table has fetched ' + config.length + ' records (' + config.total + ' total)');
});

More to come...