Skip to content

Commit

Permalink
Improve grammar, style, and consistency in the Behavior docs.
Browse files Browse the repository at this point in the history 
This commit makes relatively minor grammatical and stylitic changes
to improve the clarity of the `Behavior` docs. In addition, for the
sake of consistency, the singular forms of both `Behavior` and
`View` have been wrapped in backticks (`<code>` tags in the compiled
HTML) to match what seemed to be the preference based on the rest of
the document. Further, the established practice seemed to have been
to capitalize both "Behaviors" and "Views", but not to wrap them
in `<code>` tags, so this fixes a few stragglers in that regard.
  • Loading branch information
@thenickcox
thenickcox committed Mar 16, 2015
1 parent a2287a7 commit 18d3227
Showing 1 changed file with 38 additions and 44 deletions.
82 changes: 38 additions & 44 deletions docs/marionette.behavior.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Marionette.Behavior


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.
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.

## Documentation Index

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

## The Motivation

As you build more and more complex Views, you will find that your View becomes less about displaying model data, and more about interactions.
As you build more and more complex Views, you will find that your `View` becomes less about displaying model data, and more about interactions.

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

## Using
## Usage

Here is an example of a simple `ItemView`. Let's take a stab at simplifying it, and abstracting Behaviors from it.

Expand All @@ -41,23 +41,24 @@ var MyView = Marionette.ItemView.extend({
},

warnBeforeDestroy: function() {
alert("you are destroying all your data is now gone!");
alert("You are about to destroy all your data!");
this.destroy();
},

onShow: function() {
this.ui.destroy.tooltip({
text: "what a nice mouse you have"
text: "What a nice mouse you have."
});
}
});
```

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.
Interaction points, such as tooltips and warning messages, are generic concepts. There is no need to recode them within your Views. They are prime candidates for abstraction into a higher level, non-coupled concept, which is exactly what Behaviors provide you with.

Here is the syntax for declaring which behaviors get used within a View.
The keys in the hash are passed to `getBehaviorClass` which looks up the correct `Behavior` class.
The options for each Behavior are also passed through to the Behavior during initialization. The options are then stored within each Behavior under `options`.
Here is the syntax for declaring which behaviors get used within a View:
* The keys in the hash are passed to `getBehaviorClass`, which looks up the correct `Behavior` class.
* The options for each `Behavior` are also passed through to the `Behavior` during initialization.
* The options are then stored within each `Behavior` under `options`.

```js
var MyView = Marionette.ItemView.extend({
Expand All @@ -76,26 +77,26 @@ var MyView = Marionette.ItemView.extend({
});
```

Now let's create the `DestroyWarn` Behavior.
Now let's create the `DestroyWarn` `Behavior`.

```js
var DestroyWarn = Marionette.Behavior.extend({
// you can set default options
// just like you can in your Backbone Models
// they will be overriden if you pass in an option with the same key
// You can set default options
// just like you can in your Backbone Models.
// They will be overridden if you pass in an option with the same key.
defaults: {
"message": "you are destroying!"
"message": "You are destroying!"
},

// behaviors have events that are bound to the views DOM
// Behaviors have events that are bound to the views DOM.
events: {
"click @ui.destroy": "warnBeforeDestroy"
},

warnBeforeDestroy: function() {
alert(this.options.message);
// every Behavior has a hook into the
// view that it is attached to
// Every Behavior has a hook into the
// view that it is attached to.
this.view.destroy();
}
});
Expand All @@ -117,23 +118,22 @@ var ToolTip = Marionette.Behavior.extend({
});
```

Finally, the user must define a location for where their Behaviors are stored.
A simple example of this would look like this:
Finally, the user must define a location where their Behaviors are stored. Here is a simple example:

```js
Marionette.Behaviors.behaviorsLookup = function() {
return window.Behaviors;
}
```

In this example you would then store your Behaviors like this:
In this example, you would then store your Behaviors like this:

```js
window.Behaviors.ToolTip = ToolTip;
window.Behaviors.DestroyWarn = DestroyWarn;
```

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`:
Note that 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`:

```js
var Modal = Marionette.Behavior.extend({
Expand All @@ -145,17 +145,16 @@ var Modal = Marionette.Behavior.extend({
});
```

Nested Behaviors act as if they were direct Behaviors of the parent Behavior's view instance.
Nested Behaviors act as if they were direct Behaviors of the parent `Behavior`'s view instance.

## API

### The Event Proxy
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.
Behaviors are powered by an event proxy. This means that any events that are triggered by the view's `triggerMethod` function are passed to each `Behavior` on the `View` as well.

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.
As a real world example, whenever you would define a click event in your `View`'s `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.

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

```js
Marionette.Behavior.extend({
Expand All @@ -171,7 +170,7 @@ Marionette.Behavior.extend({


### Model Events
`modelEvents` will respond to the view's model events.
`modelEvents` will respond to the `View`'s model events.

```js
Marionette.Behavior.extend({
Expand All @@ -186,7 +185,7 @@ Marionette.Behavior.extend({
```

### Collection Events
`collectionEvents` will respond to the view's collection events.
`collectionEvents` will respond to the `View`'s collection events.

```js
Marionette.Behavior.extend({
Expand All @@ -201,23 +200,20 @@ Marionette.Behavior.extend({

### Life Cycle Methods

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.
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.

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. 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.

```js
Marionette.Behavior.extend({

onRender: function() {
//apply a jQuery plugin to every .foo item within the view
//Apply a jQuery plugin to every .foo item within the view
this.$('.foo').bar();
}
});
```

### Triggers
Any `triggers` you define on the `Behavior` will be triggered in response to the
appropriate event on the view.
Any `triggers` you define on the `Behavior` will be triggered in response to the appropriate event on the `View`.

```js
Marionette.Behavior.extend({
Expand All @@ -228,7 +224,7 @@ Marionette.Behavior.extend({
```

### Grouped Behaviors
Then `behaviors` key allows a behavior to group multiple behaviors together.
Then `behaviors` key allows a `Behavior` to group multiple behaviors together.

```js
Marionette.Behavior.extend({
Expand All @@ -239,7 +235,7 @@ Then `behaviors` key allows a behavior to group multiple behaviors together.
```

### $
`$` is a direct proxy of the view's `$` lookup method.
`$` is a direct proxy of the `View`'s `$` lookup method.

```js
Marionette.Behavior.extend({
Expand All @@ -250,8 +246,7 @@ Then `behaviors` key allows a behavior to group multiple behaviors together.
```

### $el and el
`el` is a direct proxy of the view's `el`.
Similarly, `$el` is a direct proxy of the view's `el` cached as a jQuery selector.
`el` is a direct proxy of the `View`'s `el`. Similarly, `$el` is a direct proxy of the `View`'s `el` cached as a jQuery selector.

```js
Marionette.Behavior.extend({
Expand All @@ -262,8 +257,7 @@ Marionette.Behavior.extend({
```

### defaults
`defaults` can be a `hash` or `function` to define the default options for your Behavior.
The default options will be overridden depending on what you set as the options per Behavior (this works just like a `Backbone.Model`).
`defaults` can be a `hash` or `function` to define the default options for your `Behavior`. The default options will be overridden depending on what you set as the options per `Behavior`. (This works just like a `Backbone.Model`.)

```js
Marionette.Behavior.extend({
Expand All @@ -285,7 +279,7 @@ Marionette.Behavior.extend({
```

### view
The `view` is a reference to the view instance that the Behavior is on.
The `view` is a reference to the `View` instance that the `Behavior` is attached to.

```js
Marionette.Behavior.extend({
Expand All @@ -297,9 +291,9 @@ Marionette.Behavior.extend({

### ui

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

```js
Marionette.Behavior.extend({
Expand Down

0 comments on commit 18d3227

Please sign in to comment.