Skip to content

Commit

Permalink
Adds deprecation notice regarding Callbacks.
Browse files Browse the repository at this point in the history
  • Loading branch information
@jamesplease @samccone
jamesplease authored and samccone committed Oct 7, 2014
1 parent aa80e54 commit c95ab2f
Show file tree
Hide file tree
Showing 3 changed files with 126 additions and 79 deletions.
88 changes: 51 additions & 37 deletions docs/marionette.application.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,7 @@ var MyApp = new Backbone.Marionette.Application();
## Documentation Index

* [initialize](#initialize)
* [Adding Initializers](#adding-initializers)
* [Application Event](#application-event)
* [Application Events](#application-events)
* [Starting An Application](#starting-an-application)
* [The Application Channel](#the-application-channel)
* [Event Aggregator](#event-aggregator)
Expand All @@ -35,6 +34,7 @@ var MyApp = new Backbone.Marionette.Application();
* [Get Region By Name](#get-region-by-name)
* [Removing Regions](#removing-regions)
* [Application.getOption](#applicationgetoption)
* [Adding Initializers (deprecated)](#adding-initializers)

### Initialize
Initialize is called immediately after the Application has been instantiated,
Expand All @@ -50,41 +50,7 @@ var MyApp = Marionette.Application.extend({
var myApp = new MyApp({container: '#app'});
```

## Adding Initializers

Your application needs to do useful things, like displaying content in your
regions, starting up your routers, and more. To accomplish these tasks and
ensure that your `Application` is fully configured, you can add initializer
callbacks to the application.

```js
MyApp.addInitializer(function(options){
// do useful stuff here
var myView = new MyView({
model: options.someModel
});
MyApp.mainRegion.show(myView);
});

MyApp.addInitializer(function(options){
new MyAppRouter();
Backbone.history.start();
});
```

These callbacks will be executed when you start your application,
and are bound to the application object as the context for
the callback. In other words, `this` is the `MyApp` object inside
of the initializer function.

The `options` argument is passed from the `start` method (see below).

Initializer callbacks are guaranteed to run, no matter when you
add them to the app object. If you add them before the app is
started, they will run when the `start` method is called. If you
add them after the app is started, they will run immediately.

## Application Event
## Application Events

The `Application` object raises a few events during its lifecycle, using the
[Marionette.triggerMethod](./marionette.functions.md) function. These events
Expand Down Expand Up @@ -347,3 +313,51 @@ manage regions comes from the RegionManager Class, which is documented [over her
Retrieve an object's attribute either directly from the object, or from the object's this.options, with this.options taking precedence.
More information [getOption](./marionette.functions.md)
## Adding Initializers
> Warning: deprecated
>
> This feature is deprecated, and is scheduled to be removed in version 3 of Marionette. Instead
> of Initializers, you should use events to manage start-up logic. The `start` event is an ideal
> substitute for Initializers.
>
> If you were relying on the deferred nature of Initializers in your app, you should instead
> use Promises. This might look something like the following:
>
> ```js
> doAsyncThings().then(app.start);
> ```
>
Your application needs to do useful things, like displaying content in your
regions, starting up your routers, and more. To accomplish these tasks and
ensure that your `Application` is fully configured, you can add initializer
callbacks to the application.
```js
MyApp.addInitializer(function(options){
// do useful stuff here
var myView = new MyView({
model: options.someModel
});
MyApp.mainRegion.show(myView);
});

MyApp.addInitializer(function(options){
new MyAppRouter();
Backbone.history.start();
});
```
These callbacks will be executed when you start your application,
and are bound to the application object as the context for
the callback. In other words, `this` is the `MyApp` object inside
of the initializer function.
The `options` argument is passed from the `start` method (see below).
Initializer callbacks are guaranteed to run, no matter when you
add them to the app object. If you add them before the app is
started, they will run when the `start` method is called. If you
add them after the app is started, they will run immediately.
5 changes: 5 additions & 0 deletions docs/marionette.callbacks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

# Marionette.Callbacks

> Warning: deprecated
>
> Marionette.Callbacks are deprecated, and are scheduled to be removed in the next major release of the library. Instead
> of Callbacks, you should use promises or events to manage asynchronous logic.
The `Callbacks` object assists in managing a collection of callback
methods, and executing them, in an async-safe manner.

Expand Down
112 changes: 70 additions & 42 deletions docs/marionette.module.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,14 @@ and to build individual components of your app.
* [Defining Sub-Modules](#defining-sub-modules)
* [Starting and Stopping Modules](#starting-and-stopping-modules)
* [Starting Modules](#starting-modules)
* [Module Initializers](#module-initializers)
* [Start Events](#start-events)
* [Preventing Auto-Start Of Modules](#preventing-auto-start-of-modules)
* [Starting Sub-Modules With Parent](#starting-sub-modules-with-parent)
* [Stopping Modules](#stopping-modules)
* [Module Finalizers](#module-finalizers)
* [Stop Events](#stop-events)
* [Module Initializers (deprecated)](#module-initializers)
* [Module Finalizers (deprecated)](#module-finalizers)


## Basic Usage

Expand Down Expand Up @@ -313,28 +314,6 @@ MyApp.start();
Note that modules loaded after the `MyApp.start()` call will be
immediately started.

### Module Initializers

Modules, like `Application` objects, can be configured to have initializers. And just like
an Application's initializers, module's initializers are run anytime that
the module is started. Further, there is no limit to the number of initializers it can have.

Initializers can be added in the module's definition function.

```js
MyApp.module("Foo", function(Foo){

Foo.addInitializer(function(){
// Do things once the module has started
});

Foo.addInitializer(function(){
// You can have more than one initializer
});

});
```

### Start Events

When starting a module, a "before:start" event will be triggered prior
Expand Down Expand Up @@ -474,40 +453,89 @@ This call to `stop` causes the `Bar` and `Baz` modules to both be stopped
as they are sub-modules of `Foo`. For more information on defining
sub-modules, see the section "Defining Sub-Modules".

### Module Finalizers
### Stop Events

Modules also have finalizers that work in an opposite manner to
initializers: they are called whenever a module is stopped via the `stop` method.
You can have as many finalizers as you'd like.
When stopping a module, a "before:stop" event will be triggered prior
to any of the finalizers being run. A "stop" event will then be triggered
after they have been run.

```js
var mod = MyApp.module("MyMod");

mod.on("before:stop", function(){
// do stuff before the module is stopped
});

mod.on("stop", function(){
// do stuff after the module has been stopped
});
```

### Module Initializers

> Warning: deprecated
>
> This feature is deprecated, and is scheduled to be removed in version 3 of Marionette. Instead
> of Initializers, you should use events to manage start-up logic. The `start` event is an ideal
> substitute for Initializers.
>
> If you were relying on the deferred nature of Initializers in your app, you should instead
> use Promises. This might look something like the following:
>
> ```js
> doAsyncThings().then(myModule.start);
> ```
>
Modules, like `Application` objects, can be configured to have initializers. And just like
an Application's initializers, module's initializers are run anytime that
the module is started. Further, there is no limit to the number of initializers it can have.
Initializers can be added in the module's definition function.
```js
MyApp.module("Foo", function(Foo){
Foo.addFinalizer(function(){
// Tear down, shut down and clean up the module in here
Foo.addInitializer(function(){
// Do things once the module has started
});
Foo.addFinalizer(function(){
// Do more things
Foo.addInitializer(function(){
// You can have more than one initializer
});
});
```
### Stop Events
### Module Finalizers

When stopping a module, a "before:stop" event will be triggered prior
to any of the finalizers being run. A "stop" event will then be triggered
after they have been run.
> Warning: deprecated
>
> This feature is deprecated, and is scheduled to be removed in version 3 of Marionette. Instead
> of Finalizers, you should use events to manage start-up logic. The `stop` event is an ideal
> substitute for Finalizers.
>
> If you were relying on the deferred nature of Initializers in your app, you should instead
> use Promises. This might look something like the following:
>
> ```js
> doAsyncThings().then(myModule.stop);
> ```
>
Modules also have finalizers that work in an opposite manner to
initializers: they are called whenever a module is stopped via the `stop` method.
You can have as many finalizers as you'd like.
```js
var mod = MyApp.module("MyMod");
MyApp.module("Foo", function(Foo){
mod.on("before:stop", function(){
// do stuff before the module is stopped
});
Foo.addFinalizer(function(){
// Tear down, shut down and clean up the module in here
});
Foo.addFinalizer(function(){
// Do more things
});
mod.on("stop", function(){
// do stuff after the module has been stopped
});
```

0 comments on commit c95ab2f

Please sign in to comment.