← Back to branch summary

~jderose/ubuntu/vivid/couchdb/fix-1457464

« back to all changes in this revision

Viewing changes to share/doc/src/fauxton/addons.rst

  • Committer: Package Import Robot
  • Author(s): Jason Gerard DeRose
  • Date: 2013-12-01 16:55:05 UTC
  • mfrom: (1.3.5)
  • Revision ID: package-import@ubuntu.com-20131201165505-for2toyl58mhzwj2
Tags: 1.5.0-0ubuntu1
https://launchpad.net/bugs/1254371
* New upstream release (LP: #1254371)
* Don't include `couchdb` info page in `couchdb-bin` binary package as it
  provides no meaningful benefit over the `couchdb` man page (note this change
  means we don't need to add a Build-Depends on `install-info` for Trusty)
* Remove Build-Depends: texlive-latex-base, texlive-latex-recommended,
  texlive-latex-extra, texlive-fonts-recommended, texinfo (as documentation
  thus produced doesn't get included in the binary packages anyway)
* debian/rules: don't call ./configure with --enable-strictness as we dropped
  Build-Depends on `texlive-*`, `texinfo`, plus didn't add `install-info` 
* Add Build-Depends: lsb-release (used for [vendor] info in default.ini)
* debian/rules: insert proper [vendor] info in default.ini (note this should
  be improved once there is a better mechanism upstream)
* debian/couchdb.upstart: start on filesystem and static-network-up,
  stop on deconfiguring-networking, plus add "author" line

Show diffs side-by-side

added added

removed removed

Lines of Context:
share/doc/src/fauxton/addons.rst
 
1
.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
 
2
.. use this file except in compliance with the License. You may obtain a copy of
 
3
.. the License at
 
4
..
 
5
..   http://www.apache.org/licenses/LICENSE-2.0
 
6
..
 
7
.. Unless required by applicable law or agreed to in writing, software
 
8
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 
9
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 
10
.. License for the specific language governing permissions and limitations under
 
11
.. the License.
 
12
 
 
13
 
 
14
.. _fauxton/addons:
 
15
 
 
16
===============
 
17
Writting Addons
 
18
===============
 
19
 
 
20
Addons allow you to extend Fauxton for a specific use case. Usually, they
 
21
have the following structure::
 
22
 
 
23
  + my_addon/
 
24
  | ---+ assets [optional]
 
25
  |    \ ---+ less
 
26
  |         \ ---- my_addon.less
 
27
  | ---+ templates/
 
28
  |    \ ---- my_addon.html - underscore template fragments
 
29
  | ---- resources.js - models and collections of the addon
 
30
  | ---- routes.js - URL routing for the addon
 
31
  | ---- views.js - views that the model provides
 
32
 
 
33
 
 
34
Generating an Addon
 
35
===================
 
36
 
 
37
We have a `grunt-init` template that lets you create a skeleton addon,
 
38
including all the boiler plate code. Run ``grunt-init tasks/addon`` and answer
 
39
the questions it asks to create an addon::
 
40
 
 
41
    ± grunt-init tasks/addon
 
42
    path.existsSync is now called `fs.existsSync`.
 
43
    Running "addon" task
 
44
 
 
45
    Please answer the following:
 
46
    [?] Add on Name (WickedCool) SuperAddon
 
47
    [?] Location of add ons (app/addons)
 
48
    [?] Do you need an assets folder?(for .less) (y/N)
 
49
    [?] Do you need to make any changes to the above before continuing? (y/N)
 
50
 
 
51
    Created addon SuperAddon in app/addons
 
52
 
 
53
    Done, without errors.
 
54
 
 
55
Once the addon is created add the name to the settings.json file to get it
 
56
compiled and added on the next install.
 
57
 
 
58
Routes and hooks
 
59
================
 
60
 
 
61
An addon can insert itself into Fauxton in two ways; via a route or via a hook.
 
62
 
 
63
Routes
 
64
------
 
65
 
 
66
An addon will override an existing route should one exist, but in all other
 
67
ways is just a normal backbone `route/view`. This is how you would add a whole
 
68
new feature.
 
69
 
 
70
Hooks
 
71
-----
 
72
 
 
73
Hooks let you modify/extend an existing feature. They modify a DOM element by
 
74
selector for a named set of routes, for example:
 
75
 
 
76
.. code-block:: javascript
 
77
 
 
78
    var Search = new FauxtonAPI.addon();
 
79
    Search.hooks = {
 
80
      // Render additional content into the sidebar
 
81
      "#sidebar-content": {
 
82
        routes:[
 
83
          "database/:database/_design/:ddoc/_search/:search",
 
84
          "database/:database/_design/:ddoc/_view/:view",
 
85
          "database/:database/_:handler"],
 
86
        callback: searchSidebar
 
87
      }
 
88
    };
 
89
    return Search;
 
90
 
 
91
adds the `searchSidebar` callback to `#sidebar-content` for three routes.
 
92
 
 
93
Hello world Addon
 
94
=================
 
95
 
 
96
First create the addon skeleton::
 
97
 
 
98
    ± bbb addon
 
99
    path.existsSync is now called `fs.existsSync`.
 
100
    Running "addon" task
 
101
 
 
102
    Please answer the following:
 
103
    [?] Add on Name (WickedCool) Hello
 
104
    [?] Location of add ons (app/addons)
 
105
    [?] Do you need to make any changes to the above before continuing? (y/N)
 
106
 
 
107
    Created addon Hello in app/addons
 
108
 
 
109
    Done, without errors.
 
110
 
 
111
In `app/addons/hello/templates/hello.html` place:
 
112
 
 
113
.. code-block:: html
 
114
 
 
115
    <h1>Hello!</h1>
 
116
 
 
117
Next, we'll defined a simple view in `resources.js` (for more complex addons
 
118
you may want to have a views.js) that renders that template:
 
119
 
 
120
.. code-block:: javascript
 
121
 
 
122
    define([
 
123
      "app",
 
124
      "api"
 
125
    ],
 
126
 
 
127
    function (app, FauxtonAPI) {
 
128
      var Resources = {};
 
129
 
 
130
      Resources.Hello = FauxtonAPI.View.extend({
 
131
        template: "addons/hello/templates/hello"
 
132
      });
 
133
 
 
134
      return Resources;
 
135
    });
 
136
 
 
137
 
 
138
Then define a route in `routes.js` that the addon is accessible at:
 
139
 
 
140
.. code-block:: javascript
 
141
 
 
142
    define([
 
143
      "app",
 
144
      "api",
 
145
      "addons/hello/resources"
 
146
    ],
 
147
 
 
148
    function(app, FauxtonAPI, Resources) {
 
149
      var helloRoute = function () {
 
150
        console.log('helloRoute callback yo');
 
151
        return {
 
152
          layout: "one_pane",
 
153
          crumbs: [
 
154
            {"name": "Hello","link": "_hello"}
 
155
          ],
 
156
          views: {
 
157
            "#dashboard-content": new Resources.Hello({})
 
158
          },
 
159
          apiUrl: 'hello'
 
160
        };
 
161
      };
 
162
 
 
163
      Routes = {
 
164
        "_hello": helloRoute
 
165
      };
 
166
 
 
167
      return Routes;
 
168
    });
 
169
 
 
170
 
 
171
Then wire it all together in base.js:
 
172
 
 
173
.. code-block:: javascript
 
174
 
 
175
    define([
 
176
      "app",
 
177
      "api",
 
178
      "addons/hello/routes"
 
179
    ],
 
180
 
 
181
    function(app, FauxtonAPI, HelloRoutes) {
 
182
      var Hello = new FauxtonAPI.addon();
 
183
      console.log('hello from hello');
 
184
 
 
185
      Hello.initialize = function() {
 
186
        FauxtonAPI.addHeaderLink({title: "Hello", href: "#_hello"});
 
187
      };
 
188
 
 
189
      Hello.Routes = HelloRoutes;
 
190
      console.log(Hello);
 
191
      return Hello;
 
192
    });
 
193
 
 
194
Once the code is in place include the add on in your `settings.json` so that it
 
195
gets included by the `require` task. Your addon is included in one of three
 
196
ways; a local path, a git URL or a name. Named plugins assume the plugin is in
 
197
the Fauxton base directory, addons with a git URL will be cloned into the
 
198
application, local paths will be copied. Addons included from a local path will
 
199
be cleaned out by the clean task, others are left alone.