Repository: couchdb-documentation Updated Branches: refs/heads/master fec089351 -> 59a887a97
Fix Fauxton docs Closes COUCHDB-3123 Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/59a887a9 Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/59a887a9 Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/59a887a9 Branch: refs/heads/master Commit: 59a887a97f9b6befc6de0c5bdaf17d79fb7f915d Parents: fec0893 Author: michellephung <[email protected]> Authored: Mon Sep 12 23:53:24 2016 -0400 Committer: michellephung <[email protected]> Committed: Sat Dec 3 12:47:13 2016 -0500 ---------------------------------------------------------------------- src/fauxton/addons.rst | 195 ---------------------------------------- src/fauxton/index.rst | 1 - src/fauxton/install.rst | 66 +++++--------- templates/pages/index.html | 2 +- 4 files changed, 23 insertions(+), 241 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/59a887a9/src/fauxton/addons.rst ---------------------------------------------------------------------- diff --git a/src/fauxton/addons.rst b/src/fauxton/addons.rst deleted file mode 100644 index 4269066..0000000 --- a/src/fauxton/addons.rst +++ /dev/null @@ -1,195 +0,0 @@ -.. 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. - -.. _fauxton/addons: - -=============== -Writing Addons -=============== - -Addons allow you to extend Fauxton for a specific use case. Usually, they -have the following structure:: - - + my_addon/ - | ---+ assets [optional] - | \ ---+ less - | \ ---- my_addon.less - | ---+ templates/ - | \ ---- my_addon.html - underscore template fragments - | ---- resources.js - models and collections of the addon - | ---- routes.js - URL routing for the addon - | ---- views.js - views that the model provides - -Generating an Addon -=================== - -We have a `grunt-init` template that lets you create a skeleton addon, -including all the boiler plate code. Run ``grunt-init tasks/addon`` and answer -the questions it asks to create an addon:: - - ± grunt-init tasks/addon - path.existsSync is now called `fs.existsSync`. - Running "addon" task - - 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) - - Created addon SuperAddon in app/addons - - Done, without errors. - -Once the addon is created add the name to the settings.json file to get it -compiled and added on the next install. - -Routes and hooks -================ - -An addon can insert itself into Fauxton in two ways; via a route or via a hook. - -Routes ------- - -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. - -Hooks ------ - -Hooks let you modify/extend an existing feature. They modify a DOM element by -selector for a named set of routes, for example: - -.. code-block:: javascript - - 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; - -adds the `searchSidebar` callback to `#sidebar-content` for three routes. - -Hello world Addon -================= - -First create the addon skeleton:: - - ± 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) - - Created addon Hello in app/addons - - Done, without errors. - -In `app/addons/hello/templates/hello.html` place: - -.. code-block:: html - - <h1>Hello!</h1> - -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: - -.. code-block:: javascript - - define([ - "app", - "api" - ], - - function (app, FauxtonAPI) { - var Resources = {}; - - Resources.Hello = FauxtonAPI.View.extend({ - template: "addons/hello/templates/hello" - }); - - return Resources; - }); - -Then define a route in `routes.js` that the addon is accessible at: - -.. code-block:: javascript - - define([ - "app", - "api", - "addons/hello/resources" - ], - - function(app, FauxtonAPI, Resources) { - var helloRoute = function () { - console.log('helloRoute callback yo'); - return { - layout: "one_pane", - crumbs: [ - {"name": "Hello","link": "_hello"} - ], - views: { - "#dashboard-content": new Resources.Hello({}) - }, - apiUrl: 'hello' - }; - }; - - Routes = { - "_hello": helloRoute - }; - - return Routes; - }); - -Then wire it all together in base.js: - -.. code-block:: javascript - - define([ - "app", - "api", - "addons/hello/routes" - ], - - function(app, FauxtonAPI, HelloRoutes) { - var Hello = new FauxtonAPI.addon(); - console.log('hello from hello'); - - Hello.initialize = function() { - FauxtonAPI.addHeaderLink({title: "Hello", href: "#_hello"}); - }; - - Hello.Routes = HelloRoutes; - console.log(Hello); - return Hello; - }); - -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. http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/59a887a9/src/fauxton/index.rst ---------------------------------------------------------------------- diff --git a/src/fauxton/index.rst b/src/fauxton/index.rst index 7429a86..6fe0335 100644 --- a/src/fauxton/index.rst +++ b/src/fauxton/index.rst @@ -19,4 +19,3 @@ Fauxton .. toctree:: install - addons http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/59a887a9/src/fauxton/install.rst ---------------------------------------------------------------------- diff --git a/src/fauxton/install.rst b/src/fauxton/install.rst index eabe14e..82baca3 100644 --- a/src/fauxton/install.rst +++ b/src/fauxton/install.rst @@ -12,66 +12,44 @@ .. _fauxton/install: -============ -Installation -============ - -Recent versions of `node.js`_ and `npm`_ are required. - -.. _node.js: http://nodejs.org/ -.. _npm: https://npmjs.org/doc/README.html - -Get the source -============== - -Clone the CouchDB repo:: - - $ git clone http://git-wip-us.apache.org/repos/asf/couchdb.git - $ cd couchdb - +============= Fauxton Setup ============= -Install all dependencies:: +Fauxton is included with CouchDB 2.0, so make sure CouchDB is running, then go to:: - couchdb/ $ cd src/fauxton - couchdb/src/fauxton/ $ npm install + http://127.0.0.1:5984/_utils/ -.. note:: - To avoid a npm global install add ``node_modules/.bin`` to your path:: +You can also upgrade to the latest version of Fauxton by using npm:: - export PATH=./node_modules/.bin:$PATH + $ npm install -g fauxton + $ fauxton - Or just use the wrappers in ``./bin/``. +(Recent versions of `node.js`_ and `npm`_ are required.) - Development mode, non minified files:: - - ./bin/grunt couchdebug - - Or fully compiled install:: - - ./bin/grunt couchdb - -Dev Server -========== +.. _node.js: http://nodejs.org/ +.. _npm: https://npmjs.org/doc/README.html -Using the dev server is the easiest way to use Fauxton, specially when -developing for it:: +Fauxton Visual Guide +==================== +You can find the Visual Guide here: + http://couchdb.apache.org/fauxton-visual-guide - grunt dev +Development Server +================== -Deploy Fauxton -============== +Recent versions of `node.js`_ and `npm`_ are required. -Deploy Fauxton to your local CouchDB instance: +.. _node.js: http://nodejs.org/ +.. _npm: https://npmjs.org/doc/README.html - ./bin/grunt couchapp_deploy +Using the dev server is the easiest way to use Fauxton, specially when developing for it:: -The Fauxton be available by `/fauxton/_design/fauxton/index.html -<http://localhost:5984/fauxton/_design/fauxton/index.html>`_ + $ git clone https://github.com/apache/couchdb-fauxton.git + $ npm install && npm run dev Understanding Fauxton Code layout ---------------------------------- +================================= Each bit of functionality is its own separate module or addon. http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/59a887a9/templates/pages/index.html ---------------------------------------------------------------------- diff --git a/templates/pages/index.html b/templates/pages/index.html index 819e9d3..099ea86 100644 --- a/templates/pages/index.html +++ b/templates/pages/index.html @@ -74,7 +74,7 @@ specific language governing permissions and limitations under the License. Tutorial </a> <br /> - <span class="linkdescr">start using CouchDB with Fauxton and + <span class="linkdescr">start using CouchDB with <a href="{{ pathto("fauxton/index") }}">Fauxton</a> and <a href="{{ pathto("intro/curl") }}">cURL</a></span> </p> <p class="biglink">
