[#88,doc/view][m]: document state concept and usage plus provide general overview of recline views and how Dataset Views should be structured.

src/view.js

@@ -1,16 +1,83 @@
 /*jshint multistr:true */
 
-// # Core View Functionality plus Data Explorer
+// # Recline Views
 //
-// ## Common view concepts
+// Recline Views are Backbone Views and in keeping with normal Backbone views
+// are Widgets / Components displaying something in the DOM. Like all Backbone
+// views they have a pointer to a model or a collection and is bound to an
+// element.
+//
+// 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
+//    recline-read-only class 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
 //
-// TODO
+// State information exists in order to support state serialization into the
+// url or elsewhere and reloading of application from a stored state.
 //
-// ### Read-only
+// 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`.
+// 
+// ### Writing your own Views
 //
-// TODO
+// See the existing Views.
+//
+// ----
+
+// Standard JS module setup
 this.recline = this.recline || {};
 this.recline.View = this.recline.View || {};
 
@@ -59,10 +126,20 @@ this.recline.View = this.recline.View || {};
 // ];
 // </pre>
 //
-// **state**: state config for this view. Options are:
+// **state**: standard state config for this view. This state is slightly
+//  special as it includes config of many of the subviews.
 //
-//   * readOnly: true/false (default: false) value indicating whether to
-//     operate in read-only mode (hiding all editing options).
+// <pre>
+// state = {
+//     query: {dataset query state - see dataset.queryState object}
+//     view-{id1}: {view-state for this view}
+//     view-{id2}: {view-state for }
+//     ...
+//     // Explorer
+//     currentView: id of current view (defaults to first view if not specified)
+//     readOnly: (default: false) run in read-only mode
+// }
+// </pre>
 my.DataExplorer = Backbone.View.extend({
   template: ' \
   <div class="recline-data-explorer"> \
@@ -278,7 +355,9 @@ my.DataExplorer = Backbone.View.extend({
     });
   },
 
-  // Get the current state of dataset and views 
+  // ### getState
+  //
+  // Get the current state of dataset and views (see discussion of state above)
   getState: function() {
     return this.state;
   }