Merge branch 'master' into gh-pages

_includes/example-backends-gdocs.js

@@ -0,0 +1,27 @@
+// Create a dataset with a Google Docs backend and a url to the Google Doc
+var dataset = new recline.Model.Dataset({
+    url: 'https://docs.google.com/spreadsheet/ccc?key=0Aon3JiuouxLUdGZPaUZsMjBxeGhfOWRlWm85MmV0UUE#gid=0'
+  },
+  backend='gdoc'
+);
+
+// Optional - display the results in a grid
+// Note how we can set this up before any data has arrived
+// Views will listen for query completion and update themselves automatically
+var grid = new recline.View.Grid({
+  model: dataset
+});
+$('#my-gdocs').append(grid.el);
+
+// Now do the query to the backend to load data
+dataset.fetch().done(function() {
+  dataset.query().done(function(data) {
+    // The grid will update automatically
+    // Log some data as an example
+    if (console) {
+      console.log(data);
+      console.log(dataset.currentDocuments);
+    }
+  });
+});
+

css/site/site.css

@@ -267,3 +267,7 @@ section.grey:after {
   border-radius: 0;
 }
 
+.doc-ex-rendered {
+  margin-bottom: 20px;
+}
+

example-backends.markdown

@@ -0,0 +1,114 @@
+---
+layout: container
+title: Library - Example - Loading data from different sources using Backends
+recline-deps: true
+---
+
+<div class="page-header">
+  <h1>
+    Loading data from different sources using Backends
+  </h1>
+</div>
+
+These set of examples will show you how you can load data from different
+sources such as Google Docs or the DataHub using Recline.
+
+<div class="alert alert-info">
+<p><strong>Note</strong>: often you are loading data from a given source in
+order to display it using the various Recline views. However, you can also
+happily use this data with your own code and app and this is a very common
+use-case.</p>
+<p>Moreover, Recline is designed so you need <strong>only</strong> include the
+backend and its dependencies without needing to include any of the dependencies
+for the view portion of the Recline library.</p>
+</div>
+
+## Overview
+
+Backends connect Dataset and Documents to data from a specific 'Backend' data
+source. They provide methods for loading and saving Datasets and individuals
+Documents as well as for bulk loading via a query API and doing bulk transforms
+on the backend.
+
+You can instantiate a backend directly e.g.
+
+{% highlight javascript %}
+var backend = recline.Backend.ElasticSearch();
+{% endhighlight %}
+
+But more usually the backend will be created or loaded for you by Recline and all you need is provide the identifier for that Backend e.g.
+
+{% highlight javascript %}
+var dataset = recline.Model.Dataset({
+    ...
+  },
+  'backend-identifier'
+);
+{% endhighlight %}
+
+<div class="alert alert-info">
+<strong>Backend identifiers</strong>
+How do you know the backend identifier for a given Backend? It's just the name of the 'class' in recline.Backend module (but case-insensitive). E.g. recline.Backend.ElasticSearch can be identified as 'ElasticSearch' or 'elasticsearch'.
+</div>
+
+### Included Backends
+
+* [memory: Memory Backend (local data)](docs/backend/memory.html)
+* [elasticsearch: ElasticSearch Backend](docs/backend/elasticsearch.html)
+* [dataproxy: DataProxy Backend (CSV and XLS on the Web)](docs/backend/dataproxy.html)
+* [gdoc: Google Docs (Spreadsheet) Backend](docs/backend/gdocs.html)
+* [csv: Local CSV file backend](docs/backend/localcsv.html)
+
+Backend not on this list that you would like to see? It's very easy to write a new backend -- see below for more details.
+
+## Preparing your app
+
+This is as per the [quickstart](example-quickstart.html) but the set of files is much more limited if you are just using a Backend. Specifically:
+
+{% highlight html %}
+<!-- 3rd party dependencies -->
+<script type="text/javascript" src="vendor/jquery/1.7.1/jquery.js"></script>
+<script type="text/javascript" src="vendor/underscore/1.1.6/underscore.js"></script>
+<script type="text/javascript" src="vendor/backbone/0.5.1/backbone.js"></script>
+<!-- include the backend code you need e.g. here for gdocs -->
+<script type="text/javascript" src="src/backend/base.js"></script>
+<script type="text/javascript" src="src/backend/memory.js"></script>
+<script type="text/javascript" src="src/backend/gdocs.js"></script>
+
+<!-- Or you can just include all of recline. -->
+<script type="text/javascript" src="recline.js"></script>
+{% endhighlight %}
+
+
+## Loading Data from Google Docs
+
+We will be using the [following Google
+Doc](https://docs.google.com/spreadsheet/ccc?key=0Aon3JiuouxLUdGZPaUZsMjBxeGhfOWRlWm85MmV0UUE#gid=0).
+For Recline to be able to access a Google Spreadsheet it **must** have been
+'Published to the Web' (enabled via File -> Publish to the Web menu).
+
+<div class="alert alert-info">
+<strong>Want a real world example?</strong> This <a
+href="http://okfnlabs.org/opendatacensus">Open Data Census micro-app</a> loads
+data from Google Docs and then displays it on a specialist interface combining
+a bespoke chooser and a Kartograph (svg-only) map.
+</div>
+
+{% highlight javascript %}
+{% include example-backends-gdocs.js %}
+{% endhighlight %}
+
+### Result
+
+<div id="my-gdocs" class="doc-ex-rendered">&nbsp;</div>
+
+<script type="text/javascript">
+{% include example-backends-gdocs.js %}
+</script>
+
+
+## Writing your own backend
+
+Writing your own backend is easy to do. Details of the required API are in the
+[Backend documentation](docs/backend/base.html).
+

library.html

@@ -25,7 +25,7 @@ title: Library - Home
       <h4><a href="example-quickstart.html">Recline Quickstart Guide</a></h4>
     </div>
     <div class="span4 well">
-      <h4>Loading from difference sources: Google Docs, Local CSV, DataHub</h4>
+      <h4><a href="example-backends.html">Loading from difference sources: Google Docs, Local CSV, DataHub</a></h4>
     </div>
     <div class="span3 well">
       <h4>Twitter Example</h4>
@@ -148,11 +148,11 @@ title: Library - Home
         <h4>Backends</h4>
         <ul>
           <li><a href="docs/backend/base.html">Backend: Base (base class providing a template for backends)</a></li>
-          <li><a href="docs/backend/memory.html">Backend: Memory (local data)</a></li>
+          <li><a href="docs/backend/memory.html">memory: Memory Backend (local data)</a></li>
-          <li><a href="docs/backend/elasticsearch.html">Backend: ElasticSearch</a></li>
+          <li><a href="docs/backend/elasticsearch.html">elasticsearch: ElasticSearch Backend</a></li>
-          <li><a href="docs/backend/dataproxy.html">Backend: DataProxy (CSV and XLS on the Web)</a></li>
+          <li><a href="docs/backend/dataproxy.html">dataproxy: DataProxy Backend (CSV and XLS on the Web)</a></li>
-          <li><a href="docs/backend/gdocs.html">Backend: Google Docs (Spreadsheet)</a></li>
+          <li><a href="docs/backend/gdocs.html">gdoc: Google Docs (Spreadsheet) Backend</a></li>
-          <li><a href="docs/backend/localcsv.html">Backend: Local CSV file</a></li>
+          <li><a href="docs/backend/localcsv.html">csv: Local CSV file backend</a></li>
         </ul>
       </div>
     </div>

recline.js

@@ -1192,7 +1192,7 @@ my.Grid = Backbone.View.extend({
             </th> \
           {{/notEmpty}} \
           {{#fields}} \
-            <th class="column-header {{#hidden}}hidden{{/hidden}}" data-field="{{id}}" style="width: {{width}}px;"> \
+            <th class="column-header {{#hidden}}hidden{{/hidden}}" data-field="{{id}}" style="width: {{width}}px; max-width: {{width}}px;"> \
               <div class="btn-group column-header-menu"> \
                 <a class="btn dropdown-toggle" data-toggle="dropdown"><i class="icon-cog"></i><span class="caret"></span></a> \
                 <ul class="dropdown-menu data-table-menu pull-right"> \

src/view-grid.js

@@ -145,7 +145,7 @@ my.Grid = Backbone.View.extend({
             </th> \
           {{/notEmpty}} \
           {{#fields}} \
-            <th class="column-header {{#hidden}}hidden{{/hidden}}" data-field="{{id}}" style="width: {{width}}px;"> \
+            <th class="column-header {{#hidden}}hidden{{/hidden}}" data-field="{{id}}" style="width: {{width}}px; max-width: {{width}}px;"> \
               <div class="btn-group column-header-menu"> \
                 <a class="btn dropdown-toggle" data-toggle="dropdown"><i class="icon-cog"></i><span class="caret"></span></a> \
                 <ul class="dropdown-menu data-table-menu pull-right"> \