Marionette.carpenter
A thing that makes tables
Install / Use
/learn @rapid7/Marionette.carpenterREADME
About Carpenter
Easily represent a Backbone collection as a sortable, paginated table.
One of the more common tasks when developing web applications is building tabular representations of data. Carpenter aims to make the process of building robust tables as simple as possible, while giving developers the flexibility to easily extend a table's functionality.
Features
- Searching
- Sorting
- Pagination (for both client and server-side collections)
- Custom views for table cells
- Button bar generation
Installation
Installing via Bower
The easiest way to get things rocking and rolling is with Bower:
$ bower install marionette.carpenter
That will put everything in place along with all the correct dependencies. Easy ice!
Using with RequireJS
If you'd like to use Carpenter with RequireJS, the following requirejs.config should come in handy:
requirejs.config
shim:
'backbone':
deps: ['underscore', 'jquery']
exports: 'Backbone'
'backbone.radio':
deps: ['backbone']
'underscore':
exports: '_'
'marionette':
deps: ['backbone', 'backbone.wreqr', 'backbone.babysitter']
exports: 'Marionette'
'carpenter':
deps: ['cocktail', 'backbone.radio', 'underscore.string', 'jquery-resizable-columns', 'marionette']
Note that you will also likely need to specify a paths configuration.
Installing by Hand
For an artisanal, hand-crafted, manual installation, you'll need to start by installing the...
Dependencies
You can find an up-to-date list of the libraries required by Carpenter in the bower.json file under the dependencies key. Install these as instructed in each project's README.
Manual Installation
After getting the dependencies in place, move the following files into their proper places in your project:
dist/marionette.carpenter.css- The base CSS styles for Carpenter tables.dist/marionette.carpenter.js- The main Carpenter library.
Usage
Building a table couldn't be simpler:
new Marionette.Carpenter.Controller
title: 'Users'
region: new Backbone.Marionette.Region el: '#users-table-region'
collection: usersCollection # a Backbone collection
static: true
queryParameters: {
param1: paramValue1
param2: paramValue2
}
columns: [
{ attribute: 'first_name' }
{ attribute: 'last_name' }
{ attribute: 'email' }
]
The above code creates a new table element at #users-table-region with pagination controls and sortable columns. We set the title of the table with title: 'Users', indicate the region we want the table rendered to, specify that the collection is to be paginated and sorted client-side with static: true, and then specify the attributes to load in the table with an array at columns. queryParameters optionally provides the ability to pass in additional custom parameters.
Customizing columns
The columns property is where the action's at when you're looking to specify the data that the table loads. We pass an array of objects, with each object representing a column in the table. At a minimum, we need to specify a model attribute that we wish to display for each column:
columns: [
{ attribute: 'title' }
{ attribute: 'author' }
]
This will result in two columns, with "Title" and "Author" headers, loading the data from the respective attributes in the model. We can customize the column's header label, as well:
columns: [
{
attribute: 'issueCount'
label: 'Issues'
}
]
Sortability
By default, every column is considered sortable. This is easily overridden with the sortable property in cases where we want to disallow it:
columns: [
{
attribute: 'avatar'
sortable: false
}
]
We can also customize the initial sort direction with defaultDirection:
columns: [
{
attribute: 'salary'
defaultDirection: 'desc'
}
]
Using a custom empty view
If you have a table with a collection of size 0, carpenter will render its default empty view. However, you can specify a view of your choosing to render instead.
class MyCustomEmptyView extends Marionette.ItemView
template: (data) ->
"""
<div class="custom-empty-view">
<span>This table is empty.<span>
</div>
new Marionette.Carpenter.Controller
title: 'Users'
region: new Backbone.Marionette.Region el: '#users-table-region'
collection: usersCollection # a Backbone collection
static: true
columns: [
{ attribute: 'first_name' }
{ attribute: 'last_name' }
{ attribute: 'email' }
],
emptyView: MyCustomEmptyView
Registering Handlers for the custom view
Since the custom view is a Marionette view, you can do things on the onRender and onShow callbacks as you would normally do in a marionette application. For Example:
class MyCustomCellView extends Marionette.ItemView
template: (data) ->
"""
<div class="custom-cell-view">
<span>This is a cell #{data.name}<span>
</div>
"""
ui:
span : '.custom-cell-view span'
events:
'hover @ui.span' : onHover
onHover: ->
console.log("Lets do something on hover")
onRender: ->
console.log("Lets do something special when we render the view")
Using custom cell views
Time to get fancy! Let's say we want to render something more than boring old text in one of our cells. In this case, we'd like to create a Foundation progress bar. We'll start by defining a Marionette.ItemView for the cell:
class ProjectProgressCellView extends Marionette.ItemView
template: (data) ->
"""
<div class="progress round">
<span class="meter" style="width: #{ data.percentCompleted }%"></span>
</div>
"""
We then reference that view in the relevant column's view property:
columns: [
{
attribute: 'projectTitle'
label: 'title'
}
{
attribute: 'contact'
}
{
attribute: 'percentCompleted'
label: 'progress'
view: ProjectProgressCellView
}
]
It's also possible to pass options to the view's initialize method with the viewOpts property. If our above ProjectProgressCellView accepted a class option to override the progress bar's CSS class, we could set it like so:
{
attribute: 'percentCompleted'
label: 'progress'
view: ProjectProgressCellView
viewOpts:
class: 'alert round'
}
Action Buttons
Action buttons are buttons that appear above the table.
Click Callback
You can define a click callback handler that provides you with the state of the current table.
- selectAllState - [Boolean] - True/False that represents whether or not the select all checkbox is selected.
- selectedIds - [Array<Integer>] - An array of row ids used when selectAllState is False representing rows with checkboxes selected
- deselectedIds - [Array<Integer>] - An array of row ids used when selectAllState is True representing rows with checkboxes
- selectedVisibleCollection - [Backbone.Collection] - A collection representing the current selected row that are visible on the table.
- tableCollection - [Backbone.Collection] - A collection representing the current visible rows on the table
You may also define a "class" for the button Dom element as well as a label. The containing wrapper Dom node may also have a class defined.
actionButtons = [
{
label: 'Delete'
class: 'delete'
activateOn: 'any'
click: (selectAllState, selectedIDs, deselectedIDs, selectedVisibleCollection, tableCollection) ->
console.log("Delete")
containerClass: 'action-button-right-separator'
}
{
label: 'Tag'
class: 'tag-edit'
activateOn: 'any'
click: (selectAllState, selectedIDs, deselectedIDs, selectedVisibleCollection, tableCollection) ->
console.log("Tag")
containerClass: 'action-button-tag-separator'
}
]
Enable/Disable Button
Carpenter has built in enable/disable button functionality. You can specify the following options for the 'activateOn' option
The button will be enabled if activateOn is set to:
-
'any' - If 1 or many rows are selected.
-
'many' - If more than 1 row is selected
-
'one'
