couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From benk...@apache.org
Subject fauxton commit: updated refs/heads/master to 78989e6
Date Mon, 31 Aug 2015 15:38:11 GMT
Repository: couchdb-fauxton
Updated Branches:
  refs/heads/master fa5b7add4 -> 78989e61c


Addon generator code update / doc updates

This PR updates the addon generation code:

- now includes a simple “hello world” React component and ties
it in with the route object
- remove legacy doc & code
- gets it up to our new coding standards
- makes it a lot easier to follow + understand

Also updates the writing_addons.md doc page.


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

Branch: refs/heads/master
Commit: 78989e61c1b29b10c2d8b3eff3e98090cf4c24ba
Parents: fa5b7ad
Author: Ben Keen <ben.keen@gmail.com>
Authored: Thu Aug 27 16:00:55 2015 -0700
Committer: Ben Keen <ben.keen@gmail.com>
Committed: Mon Aug 31 08:39:33 2015 -0700

----------------------------------------------------------------------
 tasks/addon/rename.json                         |   5 +-
 tasks/addon/root/base.js.underscore             |  12 +-
 .../addon/root/components.react.jsx.underscore  |  36 +++
 tasks/addon/root/resources.js.underscore        |   4 +-
 tasks/addon/root/routes.js.underscore           |  31 +--
 tasks/addon/template.js                         |  10 +-
 writing_addons.md                               | 219 +++++++------------
 7 files changed, 151 insertions(+), 166 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/78989e61/tasks/addon/rename.json
----------------------------------------------------------------------
diff --git a/tasks/addon/rename.json b/tasks/addon/rename.json
index 046ca50..5838403 100644
--- a/tasks/addon/rename.json
+++ b/tasks/addon/rename.json
@@ -1,5 +1,6 @@
 {
   "routes.js.underscore": "{%= path %}/{%= name.toLowerCase() %}/routes.js",
   "resources.js.underscore": "{%= path %}/{%= name.toLowerCase() %}/resources.js",
-  "base.js.underscore": "{%= path %}/{%= name.toLowerCase() %}/base.js"
-}
\ No newline at end of file
+  "base.js.underscore": "{%= path %}/{%= name.toLowerCase() %}/base.js",
+  "components.react.jsx.underscore": "{%= path %}/{%= name.toLowerCase() %}/components.react.jsx"
+}

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/78989e61/tasks/addon/root/base.js.underscore
----------------------------------------------------------------------
diff --git a/tasks/addon/root/base.js.underscore b/tasks/addon/root/base.js.underscore
index 7ec70a4..7a8f911 100644
--- a/tasks/addon/root/base.js.underscore
+++ b/tasks/addon/root/base.js.underscore
@@ -11,11 +11,17 @@
 // the License.
 
 define([
-  "app",
-  "api",
-  "addons/{%= name.toLowerCase() %}/routes"
+  'app',
+  'api',
+  'addons/{%= name.toLowerCase() %}/routes'
 ],
 
 function (app, FauxtonAPI, {%= name %}) {
+
+  {%= name %}.initialize = function () {
+    FauxtonAPI.addHeaderLink({title: '{%= name %}', icon: 'fonticon-attention-circled', href:
'#/example/{%= name %}'});
+  };
+
   return {%= name %};
+
 });

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/78989e61/tasks/addon/root/components.react.jsx.underscore
----------------------------------------------------------------------
diff --git a/tasks/addon/root/components.react.jsx.underscore b/tasks/addon/root/components.react.jsx.underscore
new file mode 100644
index 0000000..6556817
--- /dev/null
+++ b/tasks/addon/root/components.react.jsx.underscore
@@ -0,0 +1,36 @@
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+
+define([
+  'app',
+  'api',
+  'react',
+  'addons/{%= name.toLowerCase() %}/resources'
+],
+
+function (app, FauxtonAPI, React, {%= name %}) {
+
+  var {%= name.substr(0, 1).toUpperCase() + name.substr(1)%}Controller = React.createClass({
+    render: function () {
+      return (
+        <div>
+          <h1>Hello world!</h1>
+        </div>
+      );
+    }
+  });
+
+  return {
+    {%= name.substr(0, 1).toUpperCase() + name.substr(1)%}Controller: {%= name.substr(0,
1).toUpperCase() + name.substr(1)%}Controller
+  };
+
+});

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/78989e61/tasks/addon/root/resources.js.underscore
----------------------------------------------------------------------
diff --git a/tasks/addon/root/resources.js.underscore b/tasks/addon/root/resources.js.underscore
index 8d0ef32..2bd4316 100644
--- a/tasks/addon/root/resources.js.underscore
+++ b/tasks/addon/root/resources.js.underscore
@@ -11,8 +11,8 @@
 // the License.
 
 define([
-  "app",
-  "api"
+  'app',
+  'api'
 ],
 
 function (app, FauxtonAPI) {

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/78989e61/tasks/addon/root/routes.js.underscore
----------------------------------------------------------------------
diff --git a/tasks/addon/root/routes.js.underscore b/tasks/addon/root/routes.js.underscore
index 0fa3c6f..e35454d 100644
--- a/tasks/addon/root/routes.js.underscore
+++ b/tasks/addon/root/routes.js.underscore
@@ -11,30 +11,35 @@
 // the License.
 
 define([
-  "app",
-  "api",
-  "addons/{%= name.toLowerCase() %}/resources"
+  'app',
+  'api',
+  'addons/{%= name.toLowerCase() %}/resources',
+  'addons/{%= name.toLowerCase() %}/components.react'
 ],
-function (app, FauxtonAPI, {%= name %}) {
-  var {%= name.substr(0, 1).toUpperCase() + name.substr(1)%}RouteObject = FauxtonAPI.RouteObject.extend({
-    layout: "with_sidebar",
 
-    crumbs: [
-    ],
+function (app, FauxtonAPI, {%= name %}, Components) {
 
+  var {%= name.substr(0, 1).toUpperCase() + name.substr(1)%}RouteObject = FauxtonAPI.RouteObject.extend({
+    layout: 'one_pane',
+    roles: [],
     routes: {
+      'example/{%= name %}': 'helloWorld'
     },
 
-    roles: [],
+    initialize: function () {
+      // this executes just once, whenever the routeobject first matches a route
+    },
 
-    apiUrl: function () {
-      return ["insert url here..."];
+    helloWorld: function () {
+      this.setComponent('#dashboard-content', Components.{%= name.substr(0, 1).toUpperCase()
+ name.substr(1)%}Controller);
     },
 
-    initialize: function () {
+    apiUrl: function () {
+      return ['insert url here...'];
     }
   });
 
-  {%= name %}.RouteObjects =  [{%= name.substr(0, 1).toUpperCase() + name.substr(1)%}RouteObject];
+  {%= name %}.RouteObjects = [{%= name.substr(0, 1).toUpperCase() + name.substr(1)%}RouteObject];
+
   return {%= name %};
 });

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/78989e61/tasks/addon/template.js
----------------------------------------------------------------------
diff --git a/tasks/addon/template.js b/tasks/addon/template.js
index fd296ed..b9b4c1e 100644
--- a/tasks/addon/template.js
+++ b/tasks/addon/template.js
@@ -31,21 +31,22 @@ exports.template = function (grunt, init, done) {
     [
       {
         name: "name",
-        message: "Add on Name",
+        message: "Addon Name",
         validator: /^[\w\-\.]+$/,
         default: "WickedCool"
       },
       {
         name: "path",
-        message: "Location of add ons",
+        message: "Location of addons",
         default: "app/addons"
       },
       {
         name: "assets",
-        message: "Do you need an assets folder? (for .less)",
+        message: "Do you need an assets folder? (for .less or external JS libs)",
         default: 'y/N'
       }
     ],
+
     function (err, props) {
       // Files to copy (and process).
       var files = init.filesToCopy(props);
@@ -60,9 +61,6 @@ exports.template = function (grunt, init, done) {
         grunt.log.writeln("Created " + asspath);
       }
 
-      var tmplpath = props.path + "/" + props.name.toLowerCase() + "/templates";
-      grunt.file.mkdir(tmplpath);
-      grunt.log.writeln("Created " + tmplpath);
       // All done!
       done();
     }

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/78989e61/writing_addons.md
----------------------------------------------------------------------
diff --git a/writing_addons.md b/writing_addons.md
index 805800b..d8965ec 100644
--- a/writing_addons.md
+++ b/writing_addons.md
@@ -1,175 +1,114 @@
-# Addons
+# Writing Addons
 
-Addons allow you to extend Fauxton for a specific use case. Addons will usually have the
following structure:
+Addons allow you to extend Fauxton to do anything you may need. Perhaps you have some custom
requirements not
+met by the core script, or you just wanted to experiment. This page contains a little info
on how to write your own.
 
- * templates/
-   * my_addon.html - _underscore template fragments_
- * base.js - _entry point to the addon_
- * resources.js - _models and collections of the addon_
- * routes.js - _URL routing for the addon_
- * views.js - _views that the model provides_
+Addons are usually stored in `/app/addons` in their own subfolder, and have the following
structure:
 
- [optional]
- * assets/less
-   * my_addon.less
+* base.js - _entry point to the addon_
+* resources.js - _models and collections of the addon_
+* routes.js - _URL routing for the addon_
+* components.react.jsx - _React components (views)_
 
-## Generating an addon
+In addition, you may find you need to include CSS or external resources. For that, include
a `assets/less` or 
+`assets/external` folder.
 
-*** N.B. This is out of date: the addon should generate a React component rather than a Backbone
View *** 
 
-We have a `grunt-init` template that lets you create a skeleton addon, including all the
boiler plate code. Run
-`./node_modules/.bin/grunt-init tasks/addon` and answer the questions it asks to create an
addon:
+## Generating an Addon
 
-    $ ./node_modules/.bin/grunt-init tasks/addon
-    path.existsSync is now called `fs.existsSync`.
-    Running "addon" task
+We have a convenient `grunt-init` template that lets you create a skeleton Fauxton addon
with some boilerplate 
+code. 
 
-    Please answer the following:
-    [?] Add on Name (WickedCool) SuperAddon
-    [?] Location of add ons (app/addons)
-    [?] Do you need an assets folder?(for .less) (y/N)
-    [?] Do you need to make any changes to the above before continuing? (y/N)
+- On the command line, go to your Fauxton folder and run `./node_modules/.bin/grunt-init
tasks/addon` and 
+answer the questions it asks. It'll go something like this:
 
-    Created addon SuperAddon in app/addons
+```shell
+$ ./node_modules/.bin/grunt-init tasks/addon
+path.existsSync is now called `fs.existsSync`.
+Running "addon" task
 
-    Done, without errors.
+Please answer the following:
+[?] Add on Name (WickedCool) SuperAddon
+[?] Location of add ons (app/addons)
+[?] Do you need an assets folder?(for .less) (y/N)
+[?] Do you need to make any changes to the above before continuing? (y/N)
 
-Once the addon is created add the name to the settings.json file to get it compiled and added
on the next install.
+Created addon SuperAddon in app/addons
 
-## Routes and hooks
+Done, without errors.
+```
 
-An addon can insert itself into fauxton in two ways; via a route or via a hook.
+- Now take a look at your `app/addons/[AddonName]` folder to see what it's created for you.
Notice that at this stage, the 
+`components.react.jsx` file doesn't have a corresponding `.js` file. JSX files are files
that are precompiled into 
+javascript.
 
-### Routes
+- To add your new addon for inclusion in Fauxton, edit your `settings.json` file (or `settings.json.default`
if it 
+doesn't exist). That file defines exactly which addons gets loaded. Editing that file, you'll
see something like this 
+towards the top:
 
-An addon will override an existing route should one exist, but in all other
-ways is just a normal backbone route/view. This is how you would add a whole
-new feature.
+```javascript
+"deps": [
+  { "name": "fauxton" },
+  { "name": "components" },
+  { "name": "databases" },
+  { "name": "documents" },
+  { "name": "activetasks" },
+  { "name": "cluster" },
+  // ...
+  ],
+```
 
-### Hooks
-Hooks let you modify/extend an existing feature. They modify a DOM element by
-selector for a named set of routes, for example:
+There, just add a new row for your new addon.
 
-    var Search = new FauxtonAPI.addon();
-    Search.hooks = {
-      // Render additional content into the sidebar
-      "#sidebar-content": {
-        routes:[
-          "database/:database/_design/:ddoc/_search/:search",
-          "database/:database/_design/:ddoc/_view/:view",
-          "database/:database/_:handler"],
-        callback: searchSidebar
-      }
-    };
-    return Search;
+```javascript
+  { "name": "[AddonName]" },
+```
 
-adds the `searchSidebar` callback to `#sidebar-content` for three routes.
+(obviously replace `[AddonName]` with your addon name). 
 
-## Hello world addon
-First create the addon skeleton:
+4. Restart Fauxton (`grunt dev`) and look for a new primary nav item appear the left with
your addon name. Click that 
+and you should see a Hello World. Nice! Check out your component folder again: note that
`component.react.js` now 
+exists. That's what's being used in Fauxton when it loads in your browser.
 
-    ± bbb addon
-    path.existsSync is now called `fs.existsSync`.
-    Running "addon" task
 
-    Please answer the following:
-    [?] Add on Name (WickedCool) Hello
-    [?] Location of add ons (app/addons)
-    [?] Do you need to make any changes to the above before continuing? (y/N)
+## Some starter tips
 
-    Created addon Hello in app/addons
+### Route Objects
 
-    Done, without errors.
+Like any web app, Fauxton uses URLs (hashes, in our case) to determine what code should be
loaded to populate 
+the page. The `routes.js` file contains one or more "route objects" (it returns an array)
each of which 
+define URL path matches - just like a Backbone router.
+ 
+In this example addon, see that it has a single `example/addon` path defined. When the hash
matches that string, it will
+execute the function defined as its key. That then loads the React component found in your
`components.react.jsx` file.
 
-In `app/addons/hello/templates/hello.html` place:
+For more examples of how the Route Objects function, look through some of the existing code.

 
-    <h1>Hello!</h1>
+#### Layout templates
 
-Next, we'll defined a simple view in `resources.js` (for more complex addons
-you may want to have a views.js) that renders that template:
+You may have noticed the `layout: 'one_pane'` property of the route object in your addon.
By and large, there aren't that
+many combinations of overall page layouts within Fauxton. That setting lets you choose a
pre-existing template to help
+cut down on boilerplate code. 
 
-    define([
-      "app",
-      "api"
-    ],
+For a full list of the available templates, see the `app/templates` folder. To use any of
them, just include the 
+filename, minus the `.html` extension.
 
-    function (app, FauxtonAPI) {
-      var Resources = {};
 
-      Resources.Hello = FauxtonAPI.View.extend({
-        template: "addons/hello/templates/hello"
-      });
+### React Components & JSX
 
-      return Resources;
-    });
+If you're not familiar with React you should definitely check out their website for more
info. JSX is optional, but
+we've found it extremely useful so the compiler is baked into the `grunt dev` task and compiled
your JSX files on the 
+fly as you edit them. 
 
 
-Then define a route in `routes.js` that the addon is accessible at:
+### CSS / Less
 
-    define([
-      "app",
-      "api",
-      "addons/hello/resources"
-    ],
+Fauxton uses Less for its CSS precompilation. If you include a file with the name `[AddonName].less`
in your addon's 
+`/assets/less` folder, it will be automatically included when Fauxton starts.
 
-    function(app, FauxtonAPI, Resources) {
-      var  HelloRouteObject = FauxtonAPI.RouteObject.extend({
-        layout: "one_pane",
+### Icons
 
-        crumbs: [
-          {"name": "Hello","link": "_hello"}
-        ],
-
-        routes: {
-           "_hello": "helloRoute"
-        },
-
-        selectedHeader: "Hello",
-
-        roles: ["_admin"],
-
-        apiUrl:'hello',
-
-        initialize: function () {
-            //put common views used on all your routes here (eg:  sidebars )
-        },
-
-        helloRoute: function () {
-          this.setView("#dashboard-content", new Resources.Hello({}));
-        }
-      });
-
-      Resources.RouteObjects = [HelloRouteObject];
-
-      return Resources;
-
-    });
-
-
-
-
-Then wire it all together in base.js:
-
-    define([
-      "app",
-      "api",
-      "addons/hello/routes"
-    ],
-
-    function(app, FauxtonAPI, HelloRoutes) {
-
-      HelloRoutes.initialize = function() {
-        FauxtonAPI.addHeaderLink({title: "Hello", href: "#_hello"});
-      };
-
-      return HelloRoutes;
-    });
-
-Once the code is in place include the add on in your `settings.json` so that it
-gets included by the `require` task. Your addon is included in one of three
-ways; a local path, a git URL or a name. Named plugins assume the plugin is in
-the fauxton base directory, addons with a git URL will be cloned into the
-application, local paths will be copied. Addons included from a local path will
-be cleaned out by the clean task, others are left alone.
-
-**TODO:** addons via npm module
+Take a look at `base.js` to see how your addon was added to the primary nav. To see the list
of available icons 
+that can be used within Fauxton, check out the preview page at: 
+`http://localhost:8000/assets/fonts/styleguide/fauxtonicon-preview.html`. That's a handy
reference in case you find 
+you need an icon or two.


Mime
View raw message