Skip to content

Commit e2e14c7

Browse files
committed
Merge pull request marionettejs#2365 from benmccormick/master
Improve Behavior documentation
2 parents 4a0ceb0 + 4a38969 commit e2e14c7

File tree

2 files changed

+60
-39
lines changed

2 files changed

+60
-39
lines changed

docs/marionette.behavior.md

+52-31
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
# Marionette.Behavior
44

55

6-
A `Behavior` is an isolated set of DOM / user interactions that can be mixed into any `View` or another `Behavior`. `Behaviors` allow you to blackbox `View` specific interactions into portable logical chunks, keeping your `views` simple and your code DRY.
6+
A `Behavior` is an isolated set of DOM / user interactions that can be mixed into any `View` or another `Behavior`. Behaviors allow you to blackbox View specific interactions into portable logical chunks, keeping your Views simple and your code DRY.
77

88
## Documentation Index
99

@@ -22,13 +22,13 @@ A `Behavior` is an isolated set of DOM / user interactions that can be mixed in
2222

2323
## The Motivation
2424

25-
As you build more and more complex views, you will find that your `view` becomes less about displaying model data, and more about interactions.
25+
As you build more and more complex Views, you will find that your View becomes less about displaying model data, and more about interactions.
2626

2727
These interactions tend to be chunks of logic that you want to use in multiple views.
2828

2929
## Using
3030

31-
Here is an example of a simple `itemView`. Let's take a stab at simplifying it, and abstracting behaviors from it.
31+
Here is an example of a simple `ItemView`. Let's take a stab at simplifying it, and abstracting Behaviors from it.
3232

3333
```js
3434
var MyView = Marionette.ItemView.extend({
@@ -53,11 +53,11 @@ var MyView = Marionette.ItemView.extend({
5353
});
5454
```
5555

56-
Interaction points, such as tooltips and warning messages, are generic concepts. There is no need to recode them within your views. They are prime for abstraction into a higher level non-coupled concept, which is exactly what Behaviors provide you with.
56+
Interaction points, such as tooltips and warning messages, are generic concepts. There is no need to recode them within your Views. They are prime for abstraction into a higher level non-coupled concept, which is exactly what Behaviors provide you with.
5757

58-
Here is the syntax for declaring which behaviors get used within a view.
59-
The keys in the hash are passed to `getBehaviorClass` to lookup the correct `Behavior` class.
60-
The options for each behavior are also passed to said Behavior during initialization. The options are then stored within each behavior under `options`.
58+
Here is the syntax for declaring which behaviors get used within a View.
59+
The keys in the hash are passed to `getBehaviorClass` which looks up the correct `Behavior` class.
60+
The options for each Behavior are also passed through to the Behavior during initialization. The options are then stored within each Behavior under `options`.
6161

6262
```js
6363
var MyView = Marionette.ItemView.extend({
@@ -76,7 +76,7 @@ var MyView = Marionette.ItemView.extend({
7676
});
7777
```
7878

79-
Now let's create the `DestroyWarn` behavior.
79+
Now let's create the `DestroyWarn` Behavior.
8080

8181
```js
8282
var DestroyWarn = Marionette.Behavior.extend({
@@ -117,7 +117,7 @@ var ToolTip = Marionette.Behavior.extend({
117117
});
118118
```
119119

120-
Finally, the user must define a location for where their `behaviors` are stored.
120+
Finally, the user must define a location for where their Behaviors are stored.
121121
A simple example of this would look like this:
122122

123123
```js
@@ -126,14 +126,14 @@ A simple example of this would look like this:
126126
}
127127
```
128128

129-
In this example you would then store your behaviors like this:
129+
In this example you would then store your Behaviors like this:
130130

131131
```js
132132
window.Behaviors.ToolTip = ToolTip;
133133
window.Behaviors.DestroyWarn = DestroyWarn;
134134
```
135135

136-
Note than in addition to extending a `View` with `Behavior`, a `Behavior` can itself use other behaviors. The syntax is identical to that used for a `View`:
136+
Note than in addition to extending a `View` with `Behavior`, a `Behavior` can itself use other Behaviors. The syntax is identical to that used for a `View`:
137137

138138
```js
139139
var Modal = Marionette.Behavior.extend({
@@ -145,37 +145,30 @@ var Modal = Marionette.Behavior.extend({
145145
});
146146
```
147147

148-
Nested behaviors act as if they were direct behaviors of the parent behavior's view instance.
148+
Nested Behaviors act as if they were direct Behaviors of the parent Behavior's view instance.
149149

150150
## API
151151

152152
### The Event Proxy
153153
Behaviors are powered by an event proxy. What this means is that any events that are triggered by the view's `triggerMethod` function are passed to each Behavior on the view as well.
154154

155-
As a real world example, whenever in your `view` you would have `onShow`, your behavior can also have this `onShow` method defined. The same follows for `modelEvents` and `collectionEvents`. Think of your behavior as a receiver for all of the events on your view instance.
155+
As a real world example, whenever in your View you would define a click event in the `events` hash, you can define the same event listeners and callbacks in the behavior's `events` hash. The same follows for `modelEvents` and `collectionEvents`. Think of your behavior as a receiver for all of the events on your view instance.
156156

157157
This concept also allows for a nice decoupled method to communicate to behaviors from your view instance.
158158
You can just call from within your view `this.triggerMethod("SomeEvent", {some: "data"})`. then your `behavior` class would look like this:
159159

160160
```js
161161
Marionette.Behavior.extend({
162-
onSomeEvent: function(data) {
162+
events: {
163+
'click .foo' : 'onClick'
164+
},
165+
166+
onClick: function(data) {
163167
console.log("wow such data", data);
164168
}
165169
});
166170
```
167171

168-
### Triggers
169-
Any `triggers` you define on the `Behavior` will be triggered in response to the
170-
appropriate event on the view.
171-
172-
```js
173-
Marionette.Behavior.extend({
174-
triggers: {
175-
'click .label': 'click:label'
176-
}
177-
});
178-
```
179172

180173
### Model Events
181174
`modelEvents` will respond to the view's model events.
@@ -206,6 +199,34 @@ Marionette.Behavior.extend({
206199
});
207200
```
208201

202+
### Life Cycle Methods
203+
204+
In addition to providing the same event hashes as Views, Behaviors allow you to use the same life cycle functions that you find on Views.
205+
That means methods like `initialize`, `onRender`, `onBeforeShow`, and `onBeforeDestroy` are all valid as long as the View that implements the Behavior fires the relevant events.
206+
207+
208+
```js
209+
Marionette.Behavior.extend({
210+
211+
onRender: function() {
212+
//apply a jQuery plugin to every .foo item within the view
213+
this.$('.foo').bar();
214+
}
215+
});
216+
```
217+
218+
### Triggers
219+
Any `triggers` you define on the `Behavior` will be triggered in response to the
220+
appropriate event on the view.
221+
222+
```js
223+
Marionette.Behavior.extend({
224+
triggers: {
225+
'click .label': 'click:label'
226+
}
227+
});
228+
```
229+
209230
### Grouped Behaviors
210231
Then `behaviors` key allows a behavior to group multiple behaviors together.
211232

@@ -218,7 +239,7 @@ Then `behaviors` key allows a behavior to group multiple behaviors together.
218239
```
219240

220241
### $
221-
`$` is a direct proxy of the views `$` lookup method.
242+
`$` is a direct proxy of the view's `$` lookup method.
222243

223244
```js
224245
Marionette.Behavior.extend({
@@ -241,8 +262,8 @@ Marionette.Behavior.extend({
241262
```
242263

243264
### defaults
244-
`defaults` can be a `hash` or `function` to define the default options for your behavior.
245-
The default options will be overridden depending on what you set as the options per behavior (this works just like a `backbone.model`).
265+
`defaults` can be a `hash` or `function` to define the default options for your Behavior.
266+
The default options will be overridden depending on what you set as the options per Behavior (this works just like a `Backbone.Model`).
246267

247268
```js
248269
Marionette.Behavior.extend({
@@ -264,7 +285,7 @@ Marionette.Behavior.extend({
264285
```
265286

266287
### view
267-
The `view` is a reference to the view instance that the `behavior` is on.
288+
The `view` is a reference to the view instance that the Behavior is on.
268289

269290
```js
270291
Marionette.Behavior.extend({
@@ -277,8 +298,8 @@ Marionette.Behavior.extend({
277298
### ui
278299

279300
Behaviors can have their own ui hash, which will be mixed into the ui hash of its associated view instance.
280-
ui elements defined on either the behavior or the view will be made available within events, and triggers. They
281-
also are attached directly to the behavior and can be accessed within behavior methods as `this.ui`.
301+
ui elements defined on either the Behavior or the View will be made available within events, and triggers. They
302+
also are attached directly to the Behavior and can be accessed within Behavior methods as `this.ui`.
282303

283304
```js
284305
Marionette.Behavior.extend({

docs/marionette.behaviors.md

+8-8
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
# Marionette.Behaviors
44

5-
'Marionette.Behaviors' is a utility class that takes care of glueing your `behavior` instances to their given `View`.
6-
The most important part of this class is that you **MUST** override the class level `behaviorsLookup` method or set the option `behaviorClass` for things to work properly.
5+
'Marionette.Behaviors' is a utility class that takes care of gluing your `Behavior` instances to their given `View`.
6+
The most important thing to understand when using this class is that you **MUST** override the class level `behaviorsLookup` method or set the option `behaviorClass` for things to work properly.
77

88
## Documentation Index
99
* [API](#api)
@@ -13,21 +13,21 @@ The most important part of this class is that you **MUST** override the class le
1313

1414
## API
1515

16-
There are two class level methods that you can override on the `Behaviors` class. The rest of the class is tied to under the hood implementation details of views.
16+
There are two class level methods that you can override on the `Behaviors` class. The rest of the class is tied to under the hood implementation details of Views.
1717

1818
### behaviorsLookup
1919

20-
This method defines where your behavior classes are stored. A simple implementation might look something like this.
20+
This method defines where your Behavior classes are stored. A simple implementation might look something like this.
2121

2222
```js
2323
Marionette.Behaviors.behaviorsLookup = function() {
2424
return window.Behaviors;
2525
}
2626
```
2727

28-
By default the behaviors are looked up by their key value in a given views behavior hash.
28+
By default the Behaviors are looked up by their key value in a given View's behavior hash.
2929

30-
In this sample (using the default `getBehaviorClass` implementation) your code will expect the following behaviors to be present in `window.Behaviors.DestroyWarn` and `window.Behaviors.ToolTip`
30+
In this sample (using the default `getBehaviorClass` implementation) your code will expect the following Behaviors to be present in `window.Behaviors.DestroyWarn` and `window.Behaviors.ToolTip`
3131

3232
```js
3333
var MyView = Marionette.ItemView.extend({
@@ -44,7 +44,7 @@ var MyView = Marionette.ItemView.extend({
4444

4545
### getBehaviorClass
4646

47-
This method has a default implementation that is simple to override. It is responsible for the lookup of single behavior from within the `Behaviors.behaviorsLookup` or elsewhere.
47+
This method has a default implementation that is simple to override. It is responsible for the lookup of single Behavior from within the `Behaviors.behaviorsLookup` or elsewhere.
4848

4949
```js
5050
getBehaviorClass: function(options, key) {
@@ -58,7 +58,7 @@ getBehaviorClass: function(options, key) {
5858

5959
### behaviorClass
6060

61-
This property lets you pass a `class` in for the `behavior` to use (bypassing the normal key based lookup). This is nice to have when the behavior is a dependency of the view in [requirejs](http://requirejs.org/). Properties passed in this way will be used in `getBehaviorClass`.
61+
This property lets you pass a `class` in for the Behavior to use (bypassing the normal key based lookup). This is nice to have when the Behavior is a dependency of the View in a module system like [requirejs](http://requirejs.org/) or [browserify](http://browserify.org/). Properties passed in this way will be used in `getBehaviorClass`.
6262

6363
```js
6464
define(['marionette', 'lib/tooltip'], function(Marionette, Tooltip) {

0 commit comments

Comments
 (0)