1
=== added file 'docs/d3-component-framework.rst'
2
--- docs/d3-component-framework.rst	1970-01-01 00:00:00 +0000
3
+++ docs/d3-component-framework.rst	2012-11-28 13:27:24 +0000
4
@@ -0,0 +1,242 @@
5
1
======================
6
2
D3 Component Framework
7
3
======================
8
4
9
5
The D3 Component codebase is a small framework with the following goals:
10
6
11
7
- Support clear separation of concerns among various sections of application
12
8
  logic.
13
9
- Support incremental updates of the D3 scene.
14
10
- Allow simple configuration of features to aid in the reusability of D3
15
11
  application logic.
16
12
17
13
It accomplishes this through a number of declarative tools and suggested
18
14
patterns around application development. The document below attempts to
19
15
explain this usage as it exists today.
20
16
21
17
Module Writers Guide
22
18
====================
23
19
24
20
Using the component framework means taking advantage of the tools offered
25
21
through its module system. Components manage one or more modules, each of which
26
22
models one concern of the resultant Scene.
27
23
28
24
Modules declare events using structures dictated by the framework. Event
29
25
bindings allow the module to respond to both changes in its underlying data and
30
26
to changes in application state (through things like user interaction). It is
31
27
through these bound events that most rendering and interaction with the scene
32
28
are performed. Render becomes a rarely invoked complete redraw of the scene
33
29
while the modules themselves handle incremental updates via their event
34
30
handlers.
35
31
36
32
Component API
37
33
=============
38
34
39
35
Components support few actions (as most of the non-declarative work happens in
40
36
Modules).  Components are containers for modules and have support functions for
41
37
adding and removing modules from their management. In addition, when modules are
42
38
added options can be passed that will be made available in the modules runtime.
43
39
Modules added by via the ``addModule`` method automatically have a reference to
44
40
the component via an YUI Attribute named ``component``, and any options passed to
45
41
the addModule call in an Attribute called ``options``, which will default to an empty
46
42
object.
47
43
48
44
::
49
45
50
46
    comp = new Component();
51
47
    comp.addModule(MyModule, {foo: bar})
52
48
53
49
This example would create a new component and, using the MyModule constructor,
54
50
create an instance of this module (or use an instance if directly passed) and
55
51
set the ``component`` and ``options`` Attributes. In this example the Module would
56
52
have its ``foo`` option set to ``bar`` such that::
57
53
58
54
    modInstance.get('options.foo') === 'bar'
59
55
60
56
where modInstance is the instance created by the above example's addModule call.
61
57
62
58
Components then support rendering, drawing the scene described by any data the
63
59
modules reference. This is done in a number of phases. The first time ``render``
64
60
is called, a special ``renderOnce`` is called. This allows the component to do any
65
61
necessary setup work. Typically this will be to create some svg element and
66
62
retain a reference to it. In the context of renderOnce, ``render`` will call
67
63
``update`` on each of its modules in the order they were added. The ``update``
68
64
method is used to recalculate any intermediate state associated with rendering
69
65
the various data objects. This typically includes things like position
70
66
information. Once ``update`` has been called on the modules, each module's
71
67
``render`` method is invoked. This performs the actual drawing work. It is at
72
68
this point that any d3js synthetic events are bound to the canvas (see the
73
69
section on events below).
74
70
75
71
The most important aspect of addModule (and its inverse removeModule) is that
76
72
they properly support adding and removing event listeners. When a component's
77
73
addModule method is triggered it will bind all the declarative events of the
78
74
module, and when removeModule is called it will properly clean up event
79
75
subscriptions. Properly defining and using events is the core of the component
80
76
system and this is described in its own section.
81
77
82
78
As a final step, if the module has a ``componentBound`` callback it will be
83
79
invoked after successfully binding the module. This gives the module a
84
80
chance to initialize any data that depends on component state (which can
85
81
be obtained through ``.get('component')``).
86
82
87
83
Events
88
84
======
89
85
90
86
The heart of the component system events can be defined in a number of ways and
91
87
understanding how to take advantage of the binding features will greatly aid in
92
88
producing a system which allows for clean, clear, well separated concerns and
93
89
which in turn supports incremental rendering and data updates.
94
90
95
91
There are three categories of events supported by the component framework. They
96
92
each have their purpose and share some common syntax around expression in the
97
93
module declaration, but a module writer must understand them all to properly use
98
94
the framework.
99
95
100
96
When modules are added three sets of declarative events are bound. This is done
101
97
by including in the module an events object with the following (each optional)
102
98
sections::
103
99
104
100
  events = {scene: {},
105
101
            d3: {}
106
102
            yui: {}
107
103
            };
108
104
109
105
Most commonly there are ``scene`` events. Scene events describe YUI style event
110
106
delegation. This has advantages in that it scales well and these events can be
111
107
bound once to the top level container object of a component, and will work for
112
108
a DOM element matching its selector. Scene events are defined in one of two
113
109
ways: the first is a shorthand, the later is the more complete definition
114
110
(you'll see this in the other events types as well).
115
111
116
112
::
117
113
118
114
  scene: { selector: 'callback name on module'}
119
115
120
116
also supported is::
121
117
122
118
  scene: {selector: function() {...}}
123
119
124
120
Though the string name of a callback is preferred, as this makes the whole
125
121
set of events more easily readable. The final form is::
126
122
127
123
  scene: {selector: {callback: 'callbackName'}}
128
124
129
125
This expanded format is common to the other types of event declarations as
130
126
well as supporting options available to the other types of bindings.
131
127
132
128
Regardless of form selector is a CSS selector, typically either a ``.class`` or
133
129
an ``#id`` though pseudo-selectors work as well. With scene events these
134
130
selectors are relative to whatever container was established on initialization
135
131
of the Component. A concrete example might be::
136
132
137
133
  scene: {'.person': {click: 'personClick'}}
138
134
139
135
Which says that whenever an object in the scene with a ``person`` class is
140
136
clicked, invoke the ``personClick`` handler. Handlers all have a common signature.
141
137
To understand the calling convention you must understand a bit about how D3
142
138
data bindings work. If you're not familiar with that, please read the D3
143
139
documents related to data binding. The short version is that each DOM element
144
140
can have data associated with it through D3's sophisticated data binding model.
145
141
In the YUI world it might be common that rendered DOM elements have D3 bound
146
142
data coming from a YUI App.Model. Knowing this we can understand the calling
147
143
convention::
148
144
149
145
  callback(D3Data, component)
150
146
  Where 'this' is the DOM element that triggered the selection
151
147
  Any return is ignored.
152
148
153
149
In the near future scene events will support an additional context attribute in
154
150
their handler definition which can either be ``component`` or ``module`` and will
155
151
default to module.
156
152
157
153
.. note::
158
154
159
155
  At the time of this writing this is currently component and doesn't support
160
156
  context selection. This is addressed in a branch and when landed this note
161
157
  can be removed. It's worth noting now as the default will change.
162
158
163
159
The second type of event are D3 specific bindings. While declared in a style
164
160
similar to scene events, D3 events are bound after the modules render method is
165
161
triggered, as DOM elements must be present to be bound. There are very few cases
166
162
to prefer this style of event binding over normal scene events; however, there
167
163
are legitimate uses. If the event is a D3 synthetic event such as zoom or drag,
168
164
using D3 event bindings make sense as these cannot be delegated to using scene
169
165
events. The second case we are aware of at the time of this writing is that
170
166
certain mouse events are dealt with more easily using D3 events, as D3 uses a
171
167
well documented system of x, y position coordinates which the mouse events map
172
168
cleanly. This is a possible area for future expansion both in terms of cleaner
173
169
mouse handling and creating a possible mapping of D3 synthetics to YUI custom
174
170
events. An example of D3 events follows::
175
171
176
172
  d3: {dragstart: 'beginDrag',
177
173
       drag: 'redrawConnectors',
178
174
       dragend: 'savePosition'}
179
175
180
176
The calling convention is as above::
181
177
182
178
  callback(D3Data, component)
183
179
  'this' is the DOMElement triggering the event.
184
180
  Return value is ignored.
185
181
186
182
The final type of event is called ``yui`` events. This classification doesn't
187
183
depend on DOM selection or delegation, and is designed to provide simple
188
184
handling; its use case is YUI custom events. A common pattern for
189
185
usage might be to emit events of interest (or possible interest) from one
190
186
module and listen for those events in another. By subscribing to custom events
191
187
across modules, it's reasonably easy to extend functionality with only a loose
192
188
coupling of the modules themselves (through event names only as an example).
193
189
194
190
YUI events are defined similarly to the others but differ in some key ways.
195
191
First, they don't depend on a DOM selector, they depend on a YUI styled event
196
192
name (prefixed or otherwise). Secondly, they support a traditional YUI notion
197
193
of event phases: ``before``, ``on`` and ``after``. For additional details on how those
198
194
work, refer to the YUI event docs.
199
195
200
196
::
201
197
202
198
  yui: {'cancelAction': {callback: 'closeMenu',
203
199
                         phase: 'before',
204
200
                         context: 'module'
205
201
                         }
206
202
       }
207
203
208
204
In this example another module might fire a ``cancelAction`` event; our module
209
205
wants to respond to this by closing its menu before the triggering event is
210
206
handled, and the context (this) of the callback should be this module.
211
207
212
208
Context can either be ``component`` or ``module``, with module being the default
213
209
``this`` for handlers. Phase can be ``before``, ``on``, or ``after``, with ``on`` being
214
210
the default.
215
211
216
212
Complete Example
217
213
================
218
214
219
215
While the frameworks tests show off these features, here is a complete example of
220
216
a module with some description.
221
217
222
218
::
223
219
224
220
  TestModule = Y.Base.create('TestModule', Module, [], {
225
221
    events: {
226
222
      scene: { '.thing': {click: 'decorateThing'}},
227
223
      d3: {drag: 'dragObject'},
228
224
      yui: { cancel: 'cancelHandler'}
229
225
      },
230
226
231
227
    decorateThing: function(data, context) {
232
228
      // this is a DOM .thing element that was clicked
233
229
      // data is D3 bound data, context will be the module.
234
230
    },
235
231
236
232
    dragObject: function(data, context) {
237
233
      // this is a DOM element that had the D3.behavior.drag applied
238
234
      // and was then dragged with a mouse event.
239
235
      // data is D3 bound data, context will be the module.
240
236
    },
241
237
242
238
    cancelHandler: function(evt) {
243
239
      // this is the module
244
240
      // evt is the YUI event object
245
241
    }
246
242
  });
247
0
243
248
=== modified file 'docs/index.rst'
249
--- docs/index.rst	2012-11-01 10:56:56 +0000
250
+++ docs/index.rst	2012-11-28 13:27:24 +0000
251
@@ -3,6 +3,7 @@
252
3
   You can adapt this file completely to your liking, but it should at least
3
   You can adapt this file completely to your liking, but it should at least
253
4
   contain the root `toctree` directive.
4
   contain the root `toctree` directive.
254
5
5
255
6
======================
256
6
Juju GUI documentation
7
Juju GUI documentation
257
7
======================
8
======================
258
8
9
259
@@ -14,6 +15,7 @@
260
14
   readme
15
   readme
261
15
   style-guide
16
   style-guide
262
16
   architecture
17
   architecture
263
18
   d3-component-framework
264
17
   process
19
   process
265
18
20
266
19
Indices and tables
21
Indices and tables
Reviewer	Review Type	Date Requested	Status
Juju GUI Hackers		2012-11-28	Pending
Review via email: mp+136578@code.launchpad.net