knight/datahub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[#168,docs][s]: refactor to new layout with pages in docs.

Browse Source
This commit is contained in:
Rufus Pollock
2012-06-24 19:54:58 +01:00
parent 08fb55bd02
commit 91b97ad4e5
3 changed files with 17 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
docs/index.html Normal file
View File

@@ -0,0 +1,136 @@
---
layout: default
title: Library - Home
root: ../
---
<div class="container library">
<div class="page-header">
<h1>
Documentation
</h1>
</div>
<p>Building on <a href="http://backbonejs.com/">Backbone</a>, Recline
supplies components and structure to data-heavy applications by providing a
set of models (Dataset, Record/Row, Field) and views (Grid, Map, Graph
etc).</p>
<h2 id="concepts">Concepts and Structure</h2>
<h1><small>The Recline Library consists of 3 parts: Models, Backends and Views</small></h1>
<div class="row">
<div class="span4">
<div class="well">
<h3>Models</h3>
<p>Models help you structure your work with data by providing some standard objects such as Dataset and Record &ndash; a Dataset being a collection of Records. <a href="models.html">More &raquo;</a></p>
</div>
</div>
<div class="span4">
<div class="well">
<h3>Backends</h3>
<p>Backends connect your Models to data sources (and stores) &ndash; for example Google Docs spreadsheets, local CSV files, the DataHub, ElasticSearch etc. <a href="backends.html">More &raquo;</a></p>
</div>
</div>
<div class="span4">
<div class="well">
<h3>Views</h3>
<p>Views are user interface components for displaying, editing or interacting with the data. For example, maps, graphs, data grids or a query editor. <a href="views.html">More &raquo;</a></p>
</div>
</div>
</div>
<div id="tutorials" class="tutorials">
<h2>Tutorials</h2>
<div class="alert alert-success"><strong>Note:</strong> A quick read through of the <a href="#concepts">Concepts section</a> will
likely be useful in understanding the details of these tutorials.</div>
<div class="row">
<div class="span4">
<div class="well">
<h4><a href="example-quickstart.html">Recline Quickstart Guide</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4><a href="example-backends.html">Loading from difference sources: Google Docs, Local CSV, DataHub</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4>Twitter Example</h4>
</div>
</div>
</div>
<div class="row">
<div class="span4">
<div class="well">
<h4>Customing Display and Import using Fields</h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4>Listening to events</h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4>Setting and Getting State</h4>
</div>
</div>
</div>
<h3>Extending Recline</h3>
<div class="row">
<div class="span4">
<div class="well">
<h4>Create a new View</h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4>Create a new Backend</h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4>Create a Custom Record Object</h4>
</div>
</div>
</div>
</div>
<h2 id="docs-source">Source Docs (via Docco)</h2>
<div class="row">
<div class="span4">
<h4>Models</h4>
<ul>
<li><a href="model.html">Models</a></li>
</ul>
</div>
<div class="span4">
<h4>Backends</h4>
<ul>
<li><a href="backend/base.html">Base module providing convenience functions</a></li>
<li><a href="backend/memory.html">memory: Memory Backend (local data)</a></li>
<li><a href="backend/elasticsearch.html">elasticsearch: ElasticSearch Backend</a></li>
<li><a href="backend/dataproxy.html">dataproxy: DataProxy Backend (CSV and XLS on the Web)</a></li>
<li><a href="backend/gdocs.html">gdocs: Google Docs (Spreadsheet) Backend</a></li>
<li><a href="backend/csv.html">csv: Local CSV file backend</a></li>
</ul>
</div>
<div class="span4">
<h4>Dataset Views and Widgets</h4>
<ul>
<li><a href="view.multiview.html">MultiView View (plus common view code)</a></li>
<li><a href="view-grid.html">(Data) Grid View</a></li>
<li><a href="view-graph.html">Graph View (based on Flot)</a></li>
<li><a href="view-map.html">Map View (based on Leaflet)</a></li>
</ul>
</div>
</div>
</div> <!-- / container -->

101
docs/views.markdown Normal file
View File

@@ -0,0 +1,101 @@
---
layout: container
title: Library - Views
root: ../
---
<div class="page-header">
<h1>
Recline Views
</h1>
</div>
Recline Views are instances of Backbone Views and they act as 'WUI' (web user
interface) component displaying some model object in the DOM. Like all Backbone
views they have a pointer to a model (or a collection) and have an associated
DOM-style element (usually this element will be bound into the page at some
point).
Views provided by core Recline are crudely divided into two types:
* Dataset Views: a View intended for displaying a recline.Model.Dataset in some
fashion. Examples are the Grid, Graph and Map views.
* Widget Views: a widget used for displaying some specific (and smaller) aspect
of a dataset or the application. Examples are QueryEditor and FilterEditor
which both provide a way for editing (a part of) a `recline.Model.Query`
associated to a Dataset.
## Dataset View
These views are just Backbone views with a few additional conventions:
1. The model passed to the View should always be a recline.Model.Dataset
instance
2. Views should generate their own root element rather than having it passed
in.
3. Views should apply a css class named 'recline-{view-name-lower-cased} to the
root element (and for all CSS for this view to be qualified using this CSS
class)
4. Read-only mode: CSS for this view should respect/utilize a parent
recline-read-only class in order to trigger read-only behaviour (this class
will usually be set on some parent element of the view's root element).
5. State: state (configuration) information for the view should be stored on an
attribute named state that is an instance of a Backbone Model (or, more
speficially, be an instance of `recline.Model.ObjectState`). In addition, a
state attribute may be specified in the Hash passed to a View on
iniitialization and this information should be used to set the initial state
of the view.
Example of state would be the set of fields being plotted in a graph view.
More information about State can be found below.
To summarize some of this, the initialize function for a Dataset View should
look like:
<pre>
initialize: {
model: {a recline.Model.Dataset instance}
// el: {do not specify - instead view should create}
state: {(optional) Object / Hash specifying initial state}
...
}
</pre>
Note: Dataset Views in core Recline have a common layout on disk as follows,
where ViewName is the named of View class:
<pre>
src/view-{lower-case-ViewName}.js
css/{lower-case-ViewName}.css
test/view-{lower-case-ViewName}.js
</pre>
### State
State information exists in order to support state serialization into the url
or elsewhere and reloading of application from a stored state.
State is available not only for individual views (as described above) but for
the dataset (e.g. the current query). For an example of pulling together state
from across multiple components see `recline.View.DataExplorer`.
### Flash Messages / Notifications
To send 'flash messages' or notifications the convention is that views should
fire an event named `recline:flash` with a payload that is a flash object with
the following attributes (all optional):
* message: message to show.
* category: warning (default), success, error
* persist: if true alert is persistent, o/w hidden after 3s (default=false)
* loader: if true show a loading message
Objects or views wishing to bind to flash messages may then subscribe to these
events and take some action such as displaying them to the user. For an example
of such behaviour see the DataExplorer view.
### Writing your own Views
See the existing Views.