1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
# Addons
Addons allow you to extend Fauxton for a specific use case. Addons will usually
have the following structure:
* 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_
[optional]
* assets/less
* my_addon.less
## Generating an addon
We have a grunt task that lets you create a skeleton addon, including all the
boiler plate code. Run `bbb addon` and answer the questions it asks to create
an addon:
± bbb 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:
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:
<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:
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:
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:
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.
**TODO:** addons via npm module
|
