From c95ab2f954f006e974384b1da4b557efc076c87c Mon Sep 17 00:00:00 2001 From: Jmeas Date: Fri, 3 Oct 2014 22:58:35 -0400 Subject: [PATCH] Adds deprecation notice regarding Callbacks. --- docs/marionette.application.md | 88 +++++++++++++++----------- docs/marionette.callbacks.md | 5 ++ docs/marionette.module.md | 112 ++++++++++++++++++++------------- 3 files changed, 126 insertions(+), 79 deletions(-) diff --git a/docs/marionette.application.md b/docs/marionette.application.md index cd29ec558e..7cf5b4aa8f 100644 --- a/docs/marionette.application.md +++ b/docs/marionette.application.md @@ -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) @@ -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, @@ -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 @@ -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. diff --git a/docs/marionette.callbacks.md b/docs/marionette.callbacks.md index cadadf39f8..f37a2b7686 100644 --- a/docs/marionette.callbacks.md +++ b/docs/marionette.callbacks.md @@ -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. diff --git a/docs/marionette.module.md b/docs/marionette.module.md index bc1533ef35..a70ea4e444 100644 --- a/docs/marionette.module.md +++ b/docs/marionette.module.md @@ -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 @@ -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 @@ -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 }); ```