Revamp documentation for v4 changes

docs/backbone.radio.md

@@ -259,6 +259,9 @@ provide bindings to provide automatic event listeners and / or request handlers
 instances. This works with a bound `channelName` to let us provide listeners using the `radioEvents`
 and `radioRequests` properties.
 
+**Errors** An error will be thrown if using the radio integration unless `backbone.radio` is setup
+as a dependency.
+
 ### API
 
  * `channelName` - defines the Radio channel that will be used for the requests and/or events

docs/basics.md

@@ -16,7 +16,7 @@ patterns etc.
 
 Like [Backbone](http://backbonejs.org/#Model-extend), Marionette utilizes the
 [`_.extend`](http://underscorejs.org/#extend) function to simulate class-based
-inheritance. All built-in classes, such as `Marionette.View`, `Marionette.MnObject`
+inheritance. [All built-in classes](./classes.md), such as `Marionette.View`, `Marionette.MnObject`
 and everything that extend these provide an `extend` method for just this purpose.
 
 In the example below, we create a new pseudo-class called `MyView`:
@@ -117,10 +117,6 @@ documentation.
 When using functions to set attributes, Marionette will assign the instance of
 your new class as `this`. You can use this feature to ensure you're able to
 access your object in cases where `this` isn't what you might expect it to be.
-For example, the value or result of
-[`templateContext`](./template.md#template-context) is
-[bound to its data object](./template.md#binding-of-this) so using a
-function is the only way to access the view's context directly.
 
 ### Binding Attributes on Instantiation
 
@@ -195,5 +191,6 @@ view.checkOption();  // prints 'some text'
 
 ## Common Marionette Functionality
 
-Marionette has a few methods and core functionality that are common to all classes.
+Marionette has a few methods and core functionality that are common to [all classes](./classes.md).
+
 [Continue Reading...](./common.md).

docs/classes.md

@@ -0,0 +1,93 @@
+# Marionette Classes
+
+Marionette follows Backbone's [pseudo-class architecture](./basics.md#class-based-inheritance).
+This documentation is meant to provide a comprehensive listing of those classes so that
+the reader can have a high-level view and understand functional similarities between the classes.
+All of these classes share a [common set of functionality](./common.md).
+
+### [Marionette.View](./marionette.view.md)
+
+A `View` is used for managing portions of the DOM via a single parent DOM element or `el`.
+It provides a consistent interface for managing the content of the `el` which is typically
+administered by serializing a `Backbone.Model` or `Backbone.Collection` and rendering
+a template with the serialized data into the `View`s `el`.
+
+The `View` provides event delegation for capturing and handling DOM interactions as well as
+the ability to separate concerns into smaller, managed child views.
+
+`View` includes:
+- [The DOM API](./dom.api.md)
+- [Class Events](./events.class.md#view-events)
+- [DOM Interactions](./dom.interactions.md)
+- [Child Event Bubbling](./events.md#event-bubbling)
+- [Entity Events](./events.entity.md)
+- [View Rendering](./view.rendering.md)
+- [Prerendered Content](./dom.prerendered.md)
+- [View Lifecycle](./view.lifecycle.md)
+
+A `View` can have [`Region`s](#marionetteregion) and [`Behavior`s](#marionettebehavior)
+
+### [Marionette.CollectionView](./marionette.collectionview.md)
+
+A `CollectionView` like `View` manages a portion of the DOM via a single parent DOM element
+or `el`. This view manages an ordered set of child views that are shown within the view's `el`.
+These children are most often created to match the models of a `Backbone.Collection` though a
+`CollectionView` does not require a `collection` and can manage any set of views.
+
+`CollectionView` includes:
+- [The DOM API](./dom.api.md)
+- [Class Events](./events.class.md#collectionview-events)
+- [DOM Interactions](./dom.interactions.md)
+- [Child Event Bubbling](./events.md#event-bubbling)
+- [Entity Events](./events.entity.md)
+- [View Rendering](./view.rendering.md)
+- [Prerendered Content](./dom.prerendered.md)
+- [View Lifecycle](./view.lifecycle.md)
+
+A `CollectionView` can have [`Behavior`s](#marionettebehavior).
+
+### [Marionette.Region](./marionette.region.md)
+
+Regions provide consistent methods to manage, show and destroy views in your
+applications and views.
+
+`Region` includes:
+- [Class Events](./events.class.md#region-events)
+- [The DOM API](./dom.api.md)
+
+### [Marionette.Behavior](marionette.behavior.md)
+
+A `Behavior` provides a clean separation of concerns to your view logic, allowing you to
+share common user-facing operations between your views.
+
+`Behavior` includes:
+- [Class Events](./events.class.md#behavior-events)
+- [DOM Interactions](./dom.interactions.md)
+- [Entity Events](./events.entity.md)
+
+### [Marionette.Application](marionette.application.md)
+
+An `Application` provides hooks for organizing and initiating other elements and a view tree.
+
+`Application` includes:
+- [Class Events](./events.class.md#application-events)
+- [Radio API](./backbone.radio.md#marionette-integration)
+- [MnObject's API](./marionette.mnobject.md)
+
+An `Application` can have a single [region](./marionette.application.md#application-region).
+
+### [Marionette.MnObject](marionette.mnobject.md)
+
+`MnObject` incorporates backbone conventions `initialize`, `cid` and `extend`.
+
+`MnObject` includes:
+- [Class Events](./events.class.md#mnobject-events)
+- [Radio API](./backbone.radio.md#marionette-integration).
+
+## Routing in Marionette
+
+Users of versions of Marionette prior to v4 will notice that a router is no longer bundled.
+The [Marionette.AppRouter](https://github.com/marionettejs/marionette.approuter) was extracted
+and the core library will no longer hold an opinion on routing.
+
+[Continue Reading](./routing.md) about routing in Marionette.

docs/common.md

@@ -1,9 +1,10 @@
 # Common Marionette Functionality
 
-Marionette has a few methods that are common to all classes.
+Marionette has a few methods that are common to [all classes](./classes.md).
 
 ## Documentation Index
 
+* [initialize](#initialize)
 * [extend](#extend)
 * [Events API](#events-api)
 * [triggerMethod](#triggermethod)
@@ -16,6 +17,27 @@ Marionette has a few methods that are common to all classes.
 * [mergeOptions](#mergeoptions)
 * [The `options` Property](#the-options-property)
 
+### `initialize`
+
+Like the backbone classes, `initialize` is a method you can define on any Marionette class
+that will be called when the class is instantiated and will be passed any arguments passed
+at instantiation.  The first argument may contain [options](#getoption) the class attaches
+to the instance.
+
+```js
+import { MnObject } from 'backbone.marionette';
+
+const MyObject = MnObject.extend({
+  initialize(options, arg2) {
+    console.log(options.foo, this.getOption('foo'), arg2);
+  }
+});
+
+const myObject = new MyObject({ foo: 'bar' }, 'baz'); // logs "bar" "bar" "baz"
+```
+
+[Live example](https://jsfiddle.net/marionettejs/1ytrwyog/)
+
 ### `extend`
 
 Borrowed from backbone, `extend` is available on all class definitions for
@@ -27,12 +49,12 @@ The [Backbone.Events API](http://backbonejs.org/#Events) is available to all cla
 Each Marionette class can both `listenTo` any object with this API and have events
 triggered on the instance.
 
-**Note** The events API should not be confused with [`View` `events`](/.marionette.view.md#events)
+**Note** The events API should not be confused with [view `events`](/.dom.interactions.md#view-events)
 which capture DOM events.
 
 ### `triggerMethod`
 
-Trigger an event and a corresponding method on the object.
+Trigger an event and [a corresponding method](./events.md#onevent-binding) on the object.
 It is the same as `Backbone`'s [`trigger`](http://backbonejs.org/#Events-trigger)
 but with the additional method handler.
 
@@ -67,6 +89,8 @@ const myObj = new MyObject(); // console.log "baz"
 myObj.triggerMethod('foo', 'qux'); // console.log "qux"
 ```
 
+More information on `triggerMethod` can be found in the [Marionette events documentation](./events.md#triggermethod).
+
 ### `bindEvents`
 
 This method is used to bind any object that works with the [`Backbone.Events` API](#events-api).
@@ -99,6 +123,8 @@ any object that has Backbone.Events mixed in) to bind the events from.
 The second parameter is a hash of `{ 'event:name': 'eventHandler' }`
 configuration. A function can be supplied instead of a string handler name.
 
+**Errors** An error will be thrown if the second parameter is not an object.
+
 ### `unbindEvents`
 
 This method is used to unbind any object that works with the [`Backbone.Events` API](#events-api).
@@ -181,6 +207,8 @@ The first parameter, `channel`, is an instance from `Radio`.
 The second parameter is a hash of `{ 'request:name': 'replyHandler' }`
 configuration. A function can be supplied instead of a string handler name.
 
+**Errors** An error will be thrown if the second parameter is not an object.
+
 ### `unbindRequests`
 
 This method is used to unbind any object that works with the [`Backbone.Radio` Request API](https://github.com/marionettejs/backbone.radio#backboneradiorequests).
@@ -228,7 +256,7 @@ same hash with the function names replaced with the function references themselv
 import { View } from 'backbone.marionette';
 
 const MyView = View.extend({
-  initialize: function() {
+  initialize() {
     const hash = {
       'action:one': 'handleActionOne', // This will become a reference to `this.handleActionOne`
       'action:two': this.handleActionTwo
@@ -237,15 +265,15 @@ const MyView = View.extend({
     this.normalizedHash = this.normalizeMethods(hash);
   },
 
-  do: function(action) {
+  do(action) {
     this.normalizedHash[action]();
   },
 
-  handleActionOne: function() {
+  handleActionOne() {
     console.log('action:one was fired');
   },
 
-  handleActionTwo: function() {
+  handleActionTwo() {
     console.log('action:two was fired');
   }
 
@@ -261,24 +289,29 @@ myView.do('action:two');
 ### `getOption`
 
 To access an option, we use the `getOption` method. `getOption` will fall back
-to the value defined on the instance of the same name if not defined in the options.
+to the value of the same name defined on the instance if not defined in the options.
 
 ```javascript
 import { View } from 'backbone.marionette';
 
-const MyView = View.extend({
-  className() {
-    const defaultClass = this.getOption('defaultClass');
-    const extraClasses = this.getOption('extraClasses');
-    return [defaultClass, extraClasses].join(' ');
-  },
-  defaultClass: 'table'
+const View = View.extend({
+  classVal: 'class value',
+  initialize(){
+    this.instanceVal = 'instance value'
+  }
 });
 
-const myView = new MyView({
-  model: new MyModel(),
-  extraClasses: 'table-striped'
-});
+const view = new View({ optVal: 'option value' });
+
+view.getOption('instanceVal'); // instance value
+view.getOption('classVal'); // class value
+view.getOption('optVal'); // option value
+
+const view2 = new View({ instanceVal: 'foo', classVal: 'bar', optVal: 'baz' });
+
+view.getOption('instanceVal'); // foo
+view.getOption('classVal'); // bar
+view.getOption('optVal'); // baz
 ```
 
 [Live example](https://jsfiddle.net/marionettejs/ekvb8wwa/)
@@ -304,8 +337,9 @@ const MyObject = MnObject.extend({
 
 const model1 = new MyObject(); // => "bar"
 
-const foo;
-const model2 = new MyObject({ foo: foo }); // => "bar"
+const myObj = {};
+console.log(myObj.foo); // undefined
+const model2 = new MyObject({ foo: myObj.foo }); // => "bar"
 ```
 
 [Live example](https://jsfiddle.net/marionettejs/2ddk28ap/)
@@ -377,3 +411,10 @@ const myObject = new MyObject({
   another: 'value'
 });
 ```
+
+## Marionette Classes
+
+Marionette provides a few classes for building your view tree and
+application structure.
+
+[Continue Reading...](./classes.md).

docs/dom.api.md

@@ -5,7 +5,7 @@ jQuery and integrate with the DOM using a custom api.
 
 ## API Methods
 
-The DOM API manages the DOM on behalf of each view type and `Region`.
+The DOM API manages the DOM on behalf of [each view class and `Region`](./classes.md).
 It defines the methods that actually attach and remove views and children.
 
 [The default API](#the-default-api) depends on Backbone's jQuery `$` object however it does not
@@ -109,7 +109,7 @@ import { View } from 'backbone.marionette';
 const MyView = View.extend();
 
 MyView.setDomApi({
-  setContents: function(el, html) {
+  setContents(el, html) {
     el.innerHTML = html;
   }
 });