couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gar...@apache.org
Subject couchdb commit: updated refs/heads/fauxton-docs to f2e5ec2
Date Wed, 14 May 2014 13:31:52 GMT
Repository: couchdb
Updated Branches:
  refs/heads/fauxton-docs [created] f2e5ec2c1


First attempt at some decent fauxton documentation


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/f2e5ec2c
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/f2e5ec2c
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/f2e5ec2c

Branch: refs/heads/fauxton-docs
Commit: f2e5ec2c10902b85451eb6f662c588c54ce79705
Parents: ad8e28c
Author: Garren Smith <garren.smith@gmail.com>
Authored: Wed May 14 15:36:06 2014 +0200
Committer: Garren Smith <garren.smith@gmail.com>
Committed: Wed May 14 15:36:06 2014 +0200

----------------------------------------------------------------------
 src/fauxton/docs/routeObjects.md | 86 +++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/f2e5ec2c/src/fauxton/docs/routeObjects.md
----------------------------------------------------------------------
diff --git a/src/fauxton/docs/routeObjects.md b/src/fauxton/docs/routeObjects.md
new file mode 100644
index 0000000..cb13f47
--- /dev/null
+++ b/src/fauxton/docs/routeObjects.md
@@ -0,0 +1,86 @@
+RouteObjects
+============
+
+RouteObjects are one of the fundemental building blocks that we use in Fauxton. They help
keep a module responsive and modular. RouteObjects are used to help manage Backbone.Views
that
+are used for a specific group of routes and layout. A RouteObject is able to facilitate events
between views, load data for views as well as keep state for a specific module. 
+
+A basic RouteObject would look like this.
+
+        var  ExampleRouteObject = FauxtonAPI.RouteObject.extend({
+            // Set what the main layout will be for this page
+            // Some standard layouts are in app/addons/templates
+            layout: "with_sidebar",
+
+            // This is specific Fauxton feature, this will automatically build a set of breadcrumbs
on the layout. This is optional.
+            crumbs: [
+              {"name": "example", "link": "_example"}
+            ],
+
+
+            // Its possible to fire RouteObject events via FauxtonAPI.triggerRouteEvent,
these are handle by declaring them here. This works the same way
+            // that Backbone.Views works with events. Important to note that 'route:' must
be always be added when declaring the event in the RouteObject
+            // But don't add 'route:' when using FauxtonAPI.triggerRouteEvent
+            events: {
+              'route:example-event': "handleEvent"
+            },
+
+            // Setting this will mark a heading on the primary nav as active. This is optional.
+            selectedHeader: "example",
+
+            // Defining the roles is how Fauxton manages authentication and limits who can
access a url. 
+            // Define any couchdb role here and only users with that role assigned to them
will be able to view this RouteObject's views.
+            //It is also possible to define a role for a route.
+            roles: ["_admin"],
+
+            // Define all the routes for this RouteObject, it uses Backbone.Router, so review
its (documentation)[http://backbonejs.org/#Router]
+            // for route examples. The second route (_exampleWithAuth) uses an expanded notation
so that only users with a specific role can access
+            // that specific role
+            routes: {
+              "_example": "showExample",
+              "_exampleWithAuth": {
+                route: "exampleWithAuth",
+                roles: ['_reader']
+               }
+            },
+
+            // This will set a url for the api header. This is option. The first item in
the array is the array. The second one must always be 
+            // the documentation link. This function is optional.
+            apiUrl: function() {
+              return [this.exampleModel.url(), this.exampleModel.documentation];
+            },
+
+            // initialize like all initializes in backbone.js is called on construction of
the object. This is where all views, collections and models should be declared that 
+            // will be used throughout the lifespan of the RouteObject.
+            initialize: function () {
+              this.exampleModel = new Example();
+            },
+
+            // Establish is used to fetch all data from the server before rendering any of
the views. Return any promises that are required to have been resolved before any views get
rendered
+            // the RouteObject will make sure they are all completed before rendering views.
+            establish: {
+              return this.exampleModel.fetch();
+            },
+
+            // This is an example of a method called for a specific route. Methods like these
are used to wire up any views needed. Using the 'setView' method, we can set which views
+            // we want rendered as well as to what dom element they should be rendered in.
+            // The RouteObject will render these, as well as clean them up when they are
finished being used.
+            showExample: function () {
+              this.setView("#dashboard-content", new Log.Views.View({collection: this.logs}));
+            }
+          });
+
+General usage pattern
+
+The general usage pattern is to define a RouteObject for a group of related Routes. Often
it is just one RouteObject per addon, but some addons like the Documents addons have multiple
RouteObjects. 
+RouteObject makes fetching data for collections and models a lot easier. In the initialise
of the RouteObject, create the required collections/models. Then in each route method bind
the collections/models to the views. 
+Finally call fetch on the collections/models in the establish. 
+
+For a page with plenty of views often the views need to send "messages" or events to other
views to notify them that something has happened. This can be done by using the RouteObject
events.
+
+Rendering order
+
+The order methods are called in a RouteObject are as follows.
+* The initialise is only called once when a defined route/url in a routeObject is navigated
to for the first time. If the next url matches in the same RouteObject, the initialise will
not be called again.
+* The Routes method is then called. Here all views are created and we define what dom object
we would like the view to be attached to. The view is not yet put into the dom.
+* The RouteObjects `establish` method is then called and all collection's and model's data
are fetched. Once all that of those promises are resolved, the views will be rendered and
put into the dom.
+


Mime
View raw message