/index.html
HTML | 1903 lines | 1785 code | 103 blank | 15 comment | 0 complexity | e1de209f884b16cb7de88602fba882fc MD5 | raw file
Possible License(s): MIT
Large files files are truncated, but you can click here to view the full file
- <!doctype html>
- <!--
- backgrid
- http://github.com/wyuenho/backgrid
- Copyright (c) 2013 Jimmy Yuen Ho Wong and contributors
- Licensed under the MIT @license.
- -->
- <html lang="en">
- <head>
- <meta charset="utf-8" />
- <meta http-equiv="X-UA-Compatible" content="IE=edge;chrome=1" />
- <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
- <meta name="keywords" content="backgrid,backgrid.js,backbone,backbone.js,datagrid,grid,paginator,javascript" />
- <meta name="description" content="A powerful widget set for building data grids with Backbone.js" />
- <title>Backgrid.js - A powerful widget set for building data grids with Backbone.js</title>
- <link rel="canonical" href="http://backgridjs.com" />
- <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.2.2/css/bootstrap.min.css" />
- <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.2.2/css/bootstrap-responsive.min.css" />
- <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/select2/3.3.2/select2.min.css" />
- <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/2.36.0/codemirror.min.css" />
- <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/2.36.0/ambiance.min.css" />
- <link rel="stylesheet" href="lib/backgrid.min.css" />
- <link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.min.css" />
- <link rel="stylesheet" href="lib/extensions/text-cell/backgrid-text-cell.min.css" />
- <link rel="stylesheet" href="lib/extensions/moment-cell/backgrid-moment-cell.min.css" />
- <link rel="stylesheet" href="lib/extensions/select2-cell/backgrid-select2-cell.min.css" />
- <link rel="stylesheet" href="lib/extensions/select-all/backgrid-select-all.min.css" />
- <link rel="stylesheet" href="lib/extensions/filter/backgrid-filter.min.css" />
- <link rel="stylesheet" href="assets/css/doc.css" />
- <!--[if lt IE 9]>
- <script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
- <![endif]-->
- </head>
- <body>
- <div id="main">
- <header>
- <div class="navbar navbar-fixed-top">
- <div class="navbar-inner">
- <div class="container">
- <a href="."
- class="brand" title="A powerful widget set for building data grids with Backbone.js">Backgrid.js</a>
- <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
- <span class="icon-bar"></span>
- <span class="icon-bar"></span>
- <span class="icon-bar"></span>
- </a>
- <div class="nav-collapse collapse">
- <ul class="nav nav-pills">
- <li class="dropdown">
- <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
- Introduction
- <b class="caret"></b>
- </a>
- <ul class="dropdown-menu">
- <li><a href="#features">Features</a></li>
- <li><a href="#getting-started">Getting Started</a></li>
- <li><a href="#examples">Examples</a></li>
- </ul>
- </li>
- <li class="dropdown">
- <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
- API Reference
- <b class="caret"></b>
- </a>
- <ul class="dropdown-menu">
- <li><a href="#api-grid">Grid</a></li>
- <li><a href="#api-column">Column</a></li>
- <li><a href="#api-cell">Cell</a></li>
- <li><a href="#api-formatter">Formatter</a></li>
- <li><a href="#api-header">Header</a></li>
- <li><a href="#api-row">Row</a></li>
- <li><a href="#api-body">Body</a></li>
- <li><a href="#api-footer">Footer</a></li>
- <li class="divider"></li>
- <li><a href="#extensions"><strong class="muted">Extensions</strong></a></li>
- <li class="divider"></li>
- <li><a href="#api-select-all">SelectAll</a></li>
- <li><a href="#api-paginator">Paginator</a></li>
- <li><a href="#api-filter">Filter</a></li>
- <li><a href="#api-text-cell">TextCell</a></li>
- <li><a href="#api-moment-cell">MomentCell</a></li>
- <li><a href="#api-select2-cell">Select2Cell</a></li>
- </ul>
- </li>
- <li class="dropdown">
- <a class="dropdown-toggle" data-toggle="dropdown" data-target="#" href="#">
- More Info
- <b class="caret"></b>
- </a>
- <ul class="dropdown-menu">
- <li><a href="#styling">Styling</a></li>
- <li class="divider"></li>
- <li><a href="#faq">FAQ</a></li>
- <li><a href="https://github.com/wyuenho/backgrid/blob/master/CHANGELOG.md" target="_blank">Change Log</a></li>
- <li><a href="#license">License</a></li>
- </ul>
- </li>
- <li id="social-media">
- <a href="https://twitter.com/share" class="twitter-share-button" data-url="http://backgridjs.com" data-counturl="wyuenho.github.com/backgrid" data-via="wong_jim" data-hashtags="backgridjs,backbone_js">Tweet</a>
- <div class="g-plusone" data-size="medium"></div>
- <iframe src="http://ghbtns.com/github-btn.html?user=wyuenho&repo=backgrid&type=watch&count=true"
- allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe>
- <a href="https://coderwall.com/wyuenho"><img alt="Endorse wyuenho on Coderwall" src="http://api.coderwall.com/wyuenho/endorsecount.png" /></a>
- <iframe allowtransparency="true" frameborder="0" scrolling="no"
- style="border: 0; margin: 0 0 0 15px; padding: 0;"
- src="https://www.gittip.com/wyuenho/widget.html" width="48pt" height="22pt"></iframe>
- </li>
- </ul>
- </div>
- </div>
- <a class="visible-desktop" href="https://github.com/wyuenho/backgrid">
- <img style="position: absolute; top: 0; right: 0; border: 0;" src="assets/img/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub">
- </a>
- </div>
- </div>
- </header>
- <div class="container">
- <section class="hero-unit">
- <h1>Backgrid.js</h1>
- <p class="lead">
- Backgrid.js is a set of components for
- building <strong>semantic</strong> and <strong>easily
- stylable</strong> <strong>data grid</strong> widgets.</p>
- <p class="lead">It offers a simple, intuitive
- programming interface that makes easy things easy, but <em>hard things possible</em>
- when dealing with tabular data.</p>
- <p>
- <div class="btn-group">
- <a class="btn btn-large btn-success" href="#examples">See Examples</a>
- <a class="btn btn-large btn-primary hidden-phone hidden-tablet"
- href="https://github.com/wyuenho/backgrid/tags">Download v0.2.6</a>
- <a class="btn btn-large btn-info"
- href="https://github.com/wyuenho/backgrid/blob/0.2.6/CHANGELOG.md">What's new?</a>
- </div>
- </p>
- </section>
- <div id="features">
- <div class="page-header">
- <h1>Features</h1>
- <p>The goal of Backgrid.js is to produce a set of core Backbone UI
- elements that offer you all the basic displaying, sorting and
- editing functionalities you'd expect, and to create an
- elegant API that makes extending Backgrid.js with extra
- functionalities easy.</p>
- </div>
- <div class="row-fluid">
- <div class="span6">
- <h2>Advantages</h2>
- <ul>
- <li>No Hungarian notations.</li>
- <li>Solid foundation. Based
- on <a href="http://backbonejs.org">Backbone.js</a>.</li>
- <li>Semantic and <a href="#styling">easily stylable</a>. Just
- style with plain CSS like you would a normal HTML table.</li>
- <li>Low learning curve. Works with plain old Backbone models and
- collections. Easy things are easy, hards things possible.</li>
- <li>Highly modular and customizable. Componenets are just simple
- Backbone View classes, customization is easy if you already
- know Backbone.</li>
- <li>Lightweight. Extra features are separated
- into <a href="#extensions">extensions</a>, which keeps the
- bloat away.</li>
- <li>Good documentation.</li>
- <li>Well tested. Comes with <a href="test/" title="Jasmine Tests">100s of test cases</a>.</li>
- </ul>
- </div>
- <div class="span6">
- <h2>Supported browsers: <b style="font-size: 14px; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-weight: normal;">[1]</b></h2>
- <ul>
- <li>Internet Explorer 8+</li>
- <li>Chrome 4+</li>
- <li>Safari 4+</li>
- <li>Firefox 4+</li>
- <li>Opera 9+</li>
- </ul>
- <aside class="note">
- <h3>Notes:</h3>
- <div>1. Both the desktop and mobile versions of the above browsers are supported.</div>
- </aside>
- </div>
- </div>
- </div>
- <section id="getting-started">
- <div class="page-header">
- <h1>Getting Started</h1>
- </div>
- <div class="row-fluid">
- <div class="span6">
- <p>
- Backgrid.js depends on 3 libraries to function:
- </p>
- <ul>
- <li><a href="http://jquery.com">jquery >= 1.7.0</a></li>
- <li><a href="http://underscorejs.org">underscore.js ~ 1.4.0</a></li>
- <li><a href="http://backbonejs.org">backbone.js >= 0.9.10</a></li>
- </ul>
- <aside class="note">
- <h5>Note:</h5> If you don't care about having the latest
- versions of the dependencies, you can use the bundled libraries
- in the download package.
- </aside>
- </div>
- <div class="span6">
- <p>
- Something like the following will get
- the <strong>Backgrid.js</strong> core loaded:
- </p>
- <textarea class="code-snippet" data-mode="htmlmixed">
- <link rel="stylesheet" href="lib/backgrid.css" />
- <script src="assets/js/jquery.js"></script>
- <script src="assets/js/underscore.js"></script>
- <script src="assets/js/backbone.js"></script>
- <script src="lib/backgrid.js"></script></textarea>
- <p>Adjust the paths as needed.</p>
- </div>
- </div>
- </section>
- <section id="examples">
- <div class="page-header">
- <h1>Examples</h1>
- </div>
- <div class="row-fluid">
- <div class="span12">
- <div class="row-fluid">
- <div class="span6">
- <h2>Collection and Model</h2>
- <p>Before you can display any tabular data in a grid, you must
- first obtain the data.</p>
- <p>At the most basic level, Backgrid pretends that every row
- is a model object and the whole table is backed by a simple
- Backbone collection.</p>
- <p>Suppose we have a list of territory info objects:</p>
- </div>
- <div class="span6">
- <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
- var Territory = Backbone.Model.extend({});
- var Territories = Backbone.Collection.extend({
- model: Territory,
- url: "examples/territories.json"
- });
- var territories = new Territories();</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span12">
- <h2 id="example-1">Grid</h2>
- <p>
- The main entry point of the Backgrid package is the
- Backgrid.Grid class. You can create a default Backgrid by
- first defining some columns, and then put that list of
- columns and the collection of data into the Grid constructor
- like this:
- </p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
- var columns = [{
- name: "id", // The key of the model attribute
- label: "ID", // The name to display in the header
- editable: false, // By default every cell in a column is editable, but *ID* shouldn't be
- // Defines a cell type, and ID is displayed as an integer without the ',' separating 1000s.
- cell: Backgrid.IntegerCell.extend({
- orderSeparator: ''
- })
- }, {
- name: "name",
- label: "Name",
- // The cell type can be a reference of a Backgrid.Cell subclass, any Backgrid.Cell subclass instances like *id* above, or a string
- cell: "string" // This is converted to "StringCell" and a corresponding class in the Backgrid package namespace is looked up
- }, {
- name: "pop",
- label: "Population",
- cell: "integer" // An integer cell is a number cell that displays humanized integers
- }, {
- name: "percentage",
- label: "% of World Population",
- cell: "number" // A cell type for floating point value, defaults to have a precision 2 decimal numbers
- }, {
- name: "date",
- label: "Date",
- cell: "date",
- }, {
- name: "url",
- label: "URL",
- cell: "uri" // Renders the value in an HTML anchor element
- }];
- // Initialize a new Grid instance
- var grid = new Backgrid.Grid({
- columns: columns,
- collection: territories
- });
- // Render the grid and attach the root to your HTML document
- $("#example-1-result").append(grid.render().$el);
- // Fetch some countries from the url
- territories.fetch({reset: true});</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span12">
- <h3>Result</h3>
- <div id="example-1-result" class="backgrid-container"></div>
- <aside class="note">See <a href="http://en.wikipedia.org/wiki/List_of_countries_by_population">Wikipedia</a></aside>
- <br />
- <p>The list of column definitions Backgrid.Grid expects is
- simply a list of JSON objects, which you can hardcode into
- your HTML templates or retrieve from a server when the DOM
- is ready. Backgrid.js doesn't care where the column
- definitions come from, as long as you supply the list to the
- Grid constructor.</p>
- <p>As expected, you now have a basic editable data grid
- displayed. All the columns headers are labeled and sortable by
- default. ID cells are not editable, and all other cell types
- have reasonable validation built in. If the table gets too
- large, you get a scroll bar.</p>
- <p>Backgrid.js comes with <a href="#api-cell" title="Cells">10
- basic cell types</a> in the core
- and <a href="#api-text-cell" title="TextCell">many others
- as extensions</a>. Cell types such as
- <a href="#api-select2-cell"
- title="Select2Cell">Select2Cell</a>
- and <a href="#api-moment-cell"
- title="MomentCell">MomentCell</a> give you a much richer
- editing interface for option lists and datetime values on
- desktop browsers. In addition, there's a wide range
- of possibilities with how the data is converted for
- display and persistence by using <a href="#api-formatter"
- title="Formatter">formatters</a> or
- customizing <a href="#api-cell">cell classes</a>.</p>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span12">
- <h2 id="example-2">A More Complete Example</h2>
- <p>If you have a large result set like the above, you'd
- probably want to be able to paginate and filter your
- results. This is easily achieved in Backgrid.js.</p>
- <p>Backgrid.js comes with a number of filters and a paginator
- extension which you can load by including the following into
- your <code>head</code> tag:</p>
- <textarea class="code-snippet" data-mode="htmlmixed">
- <link rel="stylesheet" href="lib/extensions/filter/backgrid-filter.css" />
- <link rel="stylesheet" href="lib/extensions/paginator/backgrid-paginator.css" />
- <script src="assets/js/backbone-pageable.js"></script>
- <script src="lib/extensions/filter/backgrid-filter.js"></script>
- <script src="lib/extensions/paginator/backgrid-paginator.js"></script></textarea>
- <p>To use the paginator, you must first declare your
- collections to be
- a <a href="https://github.com/wyuenho/backbone-pageable/"
- title="Backbone.PageableCollection">Backbone.PageableCollection</a>,
- which is a simple subclass of the Backbone.js Collection with added
- pagination behavior.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="yes">
- var PageableTerritories = Backbone.PageableCollection.extend({
- model: Territory,
- url: "examples/pageable-territories.json",
- state: {
- pageSize: 15
- },
- mode: "client" // page entirely on the client side
- });
- var pageableTerritories = new PageableTerritories();
- // Set up a grid to use the pageable collection
- var pageableGrid = new Backgrid.Grid({
- columns: columns,
- collection: pageableTerritories
- });
- // Render the grid
- var $example2 = $("#example-2-result");
- $example2.append(pageableGrid.render().$el)
- // Initialize the paginator
- var paginator = new Backgrid.Extension.Paginator({
- collection: pageableTerritories
- });
- // Render the paginator
- $example2.append(paginator.render().$el);
- // Initialize a client-side filter to filter on the client
- // mode pageable collection's cache.
- var filter = new Backgrid.Extension.ClientSideFilter({
- collection: pageableTerritories.fullCollection,
- fields: ['name']
- });
- // Render the filter
- $example2.prepend(filter.render().$el);
- // Add some space to the filter and move it to the right
- filter.$el.css({float: "right", margin: "20px"});
- // Fetch some data
- pageableTerritories.fetch({reset: true});</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span12">
- <h3>Result</h3>
- <div id="example-2-result" class="backgrid-container"></div>
- </div>
- </div>
- </div>
- </div>
- </section>
- <section>
- <div class="page-header">
- <h1>API Reference</h1>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-grid">Grid</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Grid">Backgrid.Grid</a></li>
- </ul>
- <h3>Events</h3>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Grid-method-render">backgrid:rendered</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>How to Use the Grid</h3>
- <p>As described in the <a href="#examples">examples</a> above, a
- basic grid needs only a collection and a list of column
- definitions.</p>
- <h3>Manipulating Columns and Rows</h3>
- <p>It is very easy to insert or remove a row in a grid, you just
- have to pass a model reference
- to <a href="api/index.html#!/api/Backgrid.Grid-method-insertRow">Grid#insertRow</a>
- or <a href="api/index.html#!/api/Backgrid.Grid-method-removeRow">Grid#removeRow</a>.</p>
- <textarea class="code-snippet" data-mode="javascript">
- // Inserting rows
- grid.insertRow([{
- // model 1
- }, {
- // model 2 ... etc
- }]);
- // Remove rows
- var musketeers = grid.collection.where({ job: "Musketeer" });
- grid.removeRow(musketeers);</textarea>
- <p>Inserting and remove columns is similarly easy. You just need
- to pass some definitions
- to <a href="api/index.html#!/api/Backgrid.Grid-method-insertColumn">Grid#insertColumn</a>
- or
- <a href="api/index.html#!/api/Backgrid.Grid-method-removeColumn">Grid#removeColumn</a>.</p>
- <textarea class="code-snippet" data-mode="javascript">
- // Insert a few new columns. Make sure your model has these attributes though.
- grid.insertColumn([{
- name: "selected",
- label: "",
- cell: "boolean",
- sortable: false,
- headerCell: MySelectAllCell
- }, {
- name: "address",
- label: "Address",
- cell: "string"
- }]);
- // Remove a column
- var genderCol = grid.columns.where({ name: "gender" });
- grid.removeColumn(genderCol);</textarea>
- <h3>Customization</h3>
- <p>The various ways of customizing a grid are described in the
- following sections.</p>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-column">Columns</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Column" title="Backgrid.Column">Backgrid.Column</a></li>
- <li><a href="api/index.html#!/api/Backgrid.Columns" title="Backgrid.Columns">Backgrid.Columns</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>Column Defaults</h3>
- <p>Column defaults and required parameters are defined in
- the <a href="api/index.html#!/api/Backgrid.Column-method-initialize">Backgrid.Column#initialize</a>
- method.</p>
- <h3>Column Definition</h3>
- <p>A Column is a placeholder for a column definition.</p>
- <p>You usually don't need to create an instance of this class
- yourself, as a collection of column instances will be created for
- you from a list of column object literals you provide to the
- Backgrid.js view class constructors.</p>
- <p>Internally, columns are stored as a collection in the form of
- Backgrid.Columns. In addition, all parent views will convert the
- column definition into
- a <a href="api/index.html#!/api/Backgrid.Columns">Backgrid.Columns</a>
- collection and pass a reference to any subviews that require
- it.</p>
- <h3>Listening to Column Attribute Changes</h3>
- <p>Occasionally, you may want to listen to column attribute change
- events. In that case, you can choose to initialize a
- Backgrid.Columns collection and listen to events from the
- individual models.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var myColumns = new Backgrid.Columns({
- name: "id", label: "ID", cell: "string"
- }, {
- // ...
- });
- myColumns.on("change:renderable", function (col, colAttr) {
- if (!colAttr) {
- // hide the column
- }
- });</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-cell">Cell</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Cell">Backgrid.Cell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.DatetimeCell">Backgrid.DatetimeCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.DateCell">Backgrid.DateCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.TimeCell">Backgrid.TimeCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.NumberCell">Backgrid.NumberCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.IntegerCell">Backgrid.IntegerCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.StringCell">Backgrid.StringCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.UriCell">Backgrid.UriCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.EmailCell">Backgrid.EmailCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.BooleanCell">Backgrid.BooleanCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.SelectCell">Backgrid.SelectCell</a></li>
- <li><a href="api/index.html#!/api/Backgrid.CellEditor">Backgrid.CellEditor</a></li>
- <li><a href="api/index.html#!/api/Backgrid.InputCellEditor">Backgrid.InputCellEditor</a></li>
- <li><a href="api/index.html#!/api/Backgrid.SelectCellEditor">Backgrid.SelectCellEditor</a></li>
- </ul>
- <h3>Events</h3>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Cell-method-enterEditMode">backgrid:edit</a></li>
- <li><a href="api/index.html#!/api/Backgrid.Cell-method-enterEditMode">backgrid:editing</a></li>
- <li><a href="api/index.html#!/api/Backgrid.InputCellEditor-method-saveOrCancel">backgrid:edited</a></li>
- <li><a href="api/index.html#!/api/Backgrid.InputCellEditor-method-saveOrCancel">backgrid:error</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>Demo</h3>
- <p class="label label-success">Try them</p>
- <div id="cell-demo-grid-1" class="backgrid-container" style="height: auto"></div>
- <div id="cell-demo-grid-2" class="backgrid-container" style="height: auto"></div>
- <aside class="note">
- <h5>Note:</h5>
- <p>Backgrid.js and its author are not associated with Santa and
- santaclaus.com in any way.</p>
- </aside>
- <h3>Configuring Cells</h3>
- <p>While many built-in cells provide reasonable defaults, you may
- choose to configure them to suit your own needs.</p>
- <p>Cell types that you are most likely to configure are the
- NumberCell, DatetimeCell and SelectCell classes. Once
- configured, you may use them as the cell attribute values in
- column definitions.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var grid = new Backgrid.Grid({
- columns: [{
- name: "id",
- label: "ID",
- editable: false,
- // Dynamically defines a new cell type with new defaults.
- // ID is displayed as an integer without ','s.
- cell: Backgrid.IntegerCell.extend({
- orderSeparator: ''
- })
- }, {
- name: "lastaccessed",
- label: "Last Login Time",
- editable: false,
- cell: Backgrid.DatetimeCell.extend({
- includeMilli: true
- })
- }, {
- name: "gender",
- label: "Gender",
- cell: Backgrid.SelectCell.extend({
- // It's possible to render an option group or use a
- // function to provide option values too.
- optionValues: [["Male", "m"], ["Female", "f"]]
- })
- }],
- collection: col
- });
- </textarea>
- <p class="label label-info">Pro Tip</p>
- <p>SelectCell treats all option values as strings by default, if
- you need to persist a different type of values into your model,
- you should extend SelectCell to provide your
- own <a href="#api-formatter"
- title="Formatter">formatter</a>.</p>
- <p>See the <a href="api/index.html" title="API Doc">JSDoc</a> for
- the various Cell classes for details on what you can configure
- using this method.</p>
- <h3>Custom Cell</h3>
- <p>If the built-in and extension cell classes are not enough for
- you, you may choose to create your own cell class and supply it
- to a column definition.</p>
- <p>If your custom cell will still use a
- <code><input type="text" /></code> like the predefined
- ones for editing, you may choose to
- subclass <a href="api/index.html#!/api/Backgrid.Cell">Cell</a>
- or one of the predefined classes and simply define a className
- and a <a href="#api-formatter"
- title="Formatter">formatter</a>. In fact, most of the core cell
- classes are done this way.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- // This is how StringCell is defined.
- Backgrid.StringCell = Cell.extend({
- // Cell default class names are the lower-cased and dasherized
- // form of the the cell class names by convention.
- className: "string-cell"
- formatter: Backgrid.StringFormatter
- });</textarea>
- <p>If your cell class will render differently in display mode, you
- may simply
- override <a href="api/index.html#!/api/Backgrid.Cell-method-render">Cell#render()</a>
- in your subclass.</p>
- <h3>Custom CellEditor</h3>
- <p class="label label-warning">Advanced Usage</p>
- <p>Some cell types, like the
- <a href="#api-text-cell" title="TextCell">TextCell</a>
- extension, may only make sense if the editor is rendered in a
- modal dialog or a form element in a different part of the
- page. In that case the
- default <a href="api/index.html#!/api/Backgrid.InputCellEditor"
- title="InputCellEditor">InputCellEditor</a>, which renders a
- <code><input type="text" /></code>, will not be suitable
- and a new <a href="api/index.html#!/api/Backgrid.CellEditor"
- title="CellEditor">CellEditor</a> must be defined.</p>
- <p>A custom cell editor should subclass <a
- href="api/index.html#!/api/Backgrid.CellEditor">CellEditor</a>
- as it defines a number of required parameters in its initializer
- and clean up operations that are necessary for most cell
- editors. When a cell class enters edit mode, a new editor
- instance is constructed by given it the required parameters, and
- then a Backbone event <code>backgrid:edit</code> is fired from
- the cell instance itself. A custom cell class can act on this
- event to do anything before the cell editor is rendered.</p>
- <p>Once the cell has entered edit mode, a Backbone event
- <code>backgrid:editing</code> is fired. A custom cell class can
- then act on it to do anything after the cell editor has been
- rendered, e.g. placing the focus inside the editor.</p>
- <p>During editing, if an error is encountered (see the <a
- href="#api-formatter">formatter protocol</a> below), a cell
- editor should fire a Backbone event <code>backgrid:error</code>
- so that listeners—usually a cell instance—can
- respond appropriately. When editing is done, a cell editor
- should fire a Backbone <code>backgrid:done</code> event. A cell
- should be listening to this event so it can remove its editor
- and re-render itsef in display mode.</p>
- <p class="label label-important">Truely Advanced Hacking</p>
- <p>At the most basic level, Cells and CellEditors are simply
- <a href="http://backbonejs.org/#View"
- title="Backbone.View">Backbone.View</a> classes that are
- guaranteed to be given a number of parameters when constructed
- by <a href="api/index.html#!/api/Backgrid.Row"
- title="Row">Row</a>. You can use any Backbone.View as your Cell
- and CellEditor.</p>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-formatter">Formatter</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.CellFormatter">Backgrid.CellFormatter</a></li>
- <li><a href="api/index.html#!/api/Backgrid.DatetimeFormatter">Backgrid.DatetimeFormatter</a></li>
- <li><a href="api/index.html#!/api/Backgrid.NumberFormatter">Backgrid.NumberFormatter</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>Custom Formatters</h3>
- <p>In Backgrid.js, cell formatters serves the purpose of converting values
- between JSON value types and strings, and validation. Writing
- formatters for value conversion and validation is easy as you only
- have to conform to a very simple protocol.</p>
- <p>Any formatters must have the following two methods defined:</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var formatter = {
- // function (*): string
- fromRaw: function (rawData) { },
- // function (string): *|undefined
- toRaw: function (formattedData) { }
- };</textarea>
- <p><code>fromRaw()</code> is called by Backgrid.Cell and its
- subclasses whenever a raw model value needs to be formatted into
- a humanized form for display.</p>
- <p><code>toRaw()</code> is called by Backgrid.CellEditor and its
- subclasses whenever a user input string needs to be converted back
- to a raw JSON value for model persistence.</p>
- <h3>Validation</h3>
- <p>In addition to user input conversion, toRaw() also validates
- the user input during conversion. If the user input is invalid
- or cannot be converted to a JSON value,
- toRaw() <strong>MUST</strong> return <code>undefined</code>
- instead of throwing an Error.</p>
- <p>In addition to using formatters to do simple yes or no
- validations, if your model class has
- a <a href="http://backbonejs.org/#Model-validate"
- title="Backbone.Model#validate">validate()</a> method defined,
- it will also be used for validation after trying with the
- formatter.</p>
- <h3>Using Custom Formatters</h3>
- <p>A custom formatter can be used instead of the cell's default by
- extending the cell:</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var grid = new Backgrid.Grid({
- columns: [{
- name: "url",
- cell: "uri",
- formatter: _.extend({}, Backgrid.CellFormatter.prototype, {
- fromRaw: function (rawValue) {
- return rawValue.replace("http://", '');
- }
- })
- }],
- collection: col
- });</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-header">Header</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Header">Backgrid.Header</a></li>
- <li><a href="api/index.html#!/api/Backgrid.HeaderRow">Backgrid.HeaderRow</a></li>
- <li><a href="api/index.html#!/api/Backgrid.HeaderCell">Backgrid.HeaderCell</a></li>
- </ul>
- <h3>Events</h3>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.HeaderCell-method-sort">backgrid:sort</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>Understanding the Default Header</h3>
- <p>Backgrid.js comes with a default header section, a header row
- and a header cell implementation that renders a sorter if the
- column is sortable. The text inside the header cells comes from
- the column definitions. If a <em>label</em> is not defined in a
- column definition, its name is used as the label instead.</p>
- <p>The default header cell implementation supports sorting in
- ascending or descending order, using the column's natural
- ordering. The sorter will also allow cycling back to the
- table's default sorting order, which is sorting by the
- model <a href="http://backbonejs.org/#Model-id"
- title="Backbone.Model#id">server IDs</a>
- and <a href="http://backbonejs.org/#Model-cid"
- title="Backbone.Model#cid">client IDs</a>.</p>
- <h3>Customizing the Header</h3>
- <p>If you want to change the default sort behavior to only toggle
- between sorting in ascending or descending order, you do this
- by passing ```sortType: "toggle"``` as part of your column
- definition.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var grid = new Backgrid.Grid({
- columns: [{
- name: "id",
- label: "ID"
- },{
- name: "name",
- label: "Name"
- },{
- name: "age",
- label: "Age",
- sortTye: "toggle"
- }]
- });
- </textarea>
- <p class="label label-warning">Advanced Usage</p>
- <p>You are allow to use a different header cell class on
- columns. There is no restriction on what a header cell must do. In fact,
- any <a href="http://backbonejs.org/#View"
- title="Backbone.View">Backbone.View</a> class can be
- used. However, if you wish to modify how the sorter behaves, you
- must implement the sorting protocol. See
- the <a href="api/index.html#!/api/Backgrid.HeaderCell"
- title="Backgrid.HeaderCell API">JSDoc</a> for details.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var SelectAllHeaderCell = Backgrid.HeaderCell.extend({
- // Implement your "select all" logic here
- });
- var grid = new Backgrid.Grid({
- columns: [{
- name: "selected",
- label: "",
- sortable: false,
- cell: "boolean",
- headerCell: SelectAllHeaderCell
- }],
- collection: col
- });</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-row">Row</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Row">Backgrid.Row</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>Customizing Row</h3>
- <p class="label label-warning">Advanced Usage</p>
- <p>A row is simply an intermediary view class that constructs the
- appropriate Cell class instances for rendering the model
- columns.</p>
- <p>If you would like to override how a row is rendered, you may
- define your own Row subclass and give it to the Grid constructor
- as an option:</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var ZebraStrippingRow = Backgrid.Row.extend({
- // ...
- });
- var grid = new Backgrid.Grid({
- row: ZebraStrippingRow, // <-- Tell the new Body class to use ZebraStrippingRow to render rows.
- columns: [{
- //...
- }],
- collection: col
- });</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-body">Body</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Body">Backgrid.Body</a></li>
- </ul>
- <h3>Events</h3>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Body-method-refresh">backgrid:refresh</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>Customizing Body</h3>
- <p class="label label-important">Truely Advanced Hacking</p>
- <p>Body is the intermediary view that coordinates between the
- various parts of the grid. Specifically, the default
- implementation is responsible for re-rendering the rows when any
- model is inserted into, removed from, or reordered in the
- underlying collection. See
- the <a href="api/index.html#!/api/Backgrid.Body">JSDoc</a> for
- details.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var MyBody = Backgrid.Body.extend({
- // I really don't know why you would do this, but you can if you want
- });
- var grid = new Backgrid.Grid({
- body: MyBody,
- columns: [{
- // ...
- }],
- collection: col
- });</textarea>
- </div>
- </div>
- <div class="row-fluid">
- <div class="span2">
- <h2 id="api-footer">Footer</h2>
- <ul class="nav">
- <li><a href="api/index.html#!/api/Backgrid.Footer">Backgrid.Footer</a></li>
- </ul>
- </div>
- <div class="span10">
- <h3>Putting Things at The End of a Table</h3>
- <p>The default Footer class is an abstract class that only defines
- a number of required constructor parameters. If you wish to
- append additional information to the end of a table you must
- subclass Footer and supply the class to the Grid
- constructor.</p>
- <textarea class="code-snippet" data-mode="javascript" data-eval="no">
- var CaptionFooter = Backgrid.Footer.extend({
- render: function () {
- this.$el.html("<tr><td colspan='6'>Hello World!</td></tr>");
- return this;
- }
- });
- var grid = new Backgrid.Grid({
- columns: [{
- //...
- }],
- collection: col,
- footer: CaptionFooter // <--
- });</textarea>
- <p>Very often, you'll want to append a paginator to the end
- of your table if there are too many rows. For this, there's already
- a <a href="#api-paginator">paginator extension</a> provided for you.</p>
- </div>
- </div>
- </section>
- <section id="extensions">
- <div class="page-header">
- <h1>Extensions</h1>
- <p>It is not necessary to create an extension project if you simply
- want to customize or extend some Backgrid.js classes for your own
- private use; however, if you have one or more Backgrid.js
- components that add new features to the core, you may consider
- packaging them up to share with the world.</p>
- <p>A Backgrid.js extension is a directory structure that packages
- the necessary JS, CSS, tests, and document files.</p>
- <p>To create an extension, clone the tree into your file system and
- type:</p>
- <textarea class="code-snippet" data-mode="shell">
- $ cd backgrid
- $ make extension</textarea>
- <p>A new extension directory structure should have been created for
- you under <code>src/extensions</code>. The current implementation
- of <code>make extension</code> only creates a blank directory
- filled with a number of blank files for you. You should take a
- look at other extensions to copy what you need. e.g. Makefile,
- .gitignore.</p>
- <h2>Extension Development Guide</h2>
- <p>The following is a guideline for extension development:</p>
- <ul>
- <li>There should be 1 .js file and 1 .css file. If your code base
- gets too large, consider breaking it into multiple extensions.</li>
- <li>There should be 1 .min.js file and 1 .min.css file produced
- for distribution.</li>
- <li>Your Makefile should emulate other extensions as closely
- as possible. Specifically, you should have a <code>dist</code>
- rule that will take a <code>DIST_DIR</code> variable from
- top-level make invocations and copy the output files to the
- …
Large files files are truncated, but you can click here to view the full file