Marionette.Region ================= Region managers provide a consistent way to manage your views and show / close them in your application. They use a jQuery selector to show your views in the correct place. They also call extra methods on your views to facilitate additional functionality. Documentation Index ------------------- - `Defining An Application Region <#defining-an-application-region>`_ - `Initialize A Region With An ``el`` <#initialize-a-region-with-an-el>`_ - `Basic Use <#basic-use>`_ - ```reset`` A Region <#reset-a-region>`_ - `Set How View's ``el`` Is Attached <#set-how-views-el-is-attached>`_ - `Attach Existing View <#attach-existing-view>`_ - `Set ``currentView`` On Initialization <#set-currentview-on-initialization>`_ - `Call ``attachView`` On Region <#call-attachview-on-region>`_ - `Region Events And Callbacks <#region-events-and-callbacks>`_ - `View Callbacks And Events For Regions <#view-callbacks-and-events-for-regions>`_ - `Custom Region Types <#custom-region-types>`_ - `Attaching Custom Region Types <#attaching-custom-region-types>`_ - `Instantiate Your Own Region <#instantiate-your-own-region>`_ Defining An Application Region ------------------------------ Regions can be added to the application by calling the ``addRegions`` method on your application instance. This method expects a single hash parameter, with named regions and either jQuery selectors or ``Region`` objects. You may call this method as many times as you like, and it will continue adding regions to the app. ``js MyApp.addRegions({ mainRegion: "#main-content", navigationRegion: "#navigation" });`` As soon as you call ``addRegions``, your region managers are available on your app object. In the above, example ``MyApp.mainRegion`` and ``MyApp.navigationRegion`` would be available for use immediately. If you specify the same region name twice, the last one in wins. Initialize A Region With An ``el`` ---------------------------------- You can specify an ``el`` for the region manager to manage at the time that the region manager is instantiated: ``js var mgr = new Backbone.Marionette.Region({ el: "#someElement" });`` Basic Use --------- Once a region manager has been defined, you can call the ``show`` and ``close`` methods on it to render and display a view, and then to close that view: \`\`\`js var myView = new MyView(); // render and display the view MyApp.mainRegion.show(myView); // closes the current view MyApp.mainRegion.close(); \`\`\` If you replace the current view with a new view by calling ``show``, it will automatically close the previous view. \`\`\`js // show the first view var myView = new MyView(); MyApp.mainRegion.show(myView); // replace view with another. the // ``close`` method is called for you var anotherView = new AnotherView(); MyApp.mainRegion.show(anotherView); \`\`\` ``reset`` A Region ------------------ A region can be ``reset`` at any time. This will close any existing view that is being displayed, and delete the cached ``el``. The next time the region is used to show a view, the region's ``el`` will be queried from the DOM. ``js myRegion.reset();`` This is useful for scenarios where a region is re-used across view instances, or in unit testing. Set How View's ``el`` Is Attached --------------------------------- If you need to change how the view is attached to the DOM when showing a view via a region, override the ``open`` method of the region. This method receives one parameter - the view to show. The default implementation of ``open`` is: ``js Marionette.Region.prototype.open = function(view){ this.$el.html(view.el); }`` This will replace the contents of the region with the view's ``el`` / content. You can change to this be anything you wish, though, facilitating transition effects and more. ``js Marionette.Region.prototype.open = function(view){ this.$el.hide(); this.$el.html(view.el); this.$el.slideDown("fast"); }`` This example will cause a view to slide down from the top of the region, instead of just appearing in place. Attach Existing View -------------------- There are some scenarios where it's desirable to attach an existing view to a region manager, without rendering or showing the view, and without replacing the HTML content of the region. For example, SEO and accessibiliy often need HTML to be generated by the server, and progressive enhancement of the HTML. There are two ways to accomplish this: - set the ``currentView`` in the region manager's constructor - call ``attachView`` on the region manager instance Set ``currentView`` On Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \`\`\`js var myView = new MyView({ el: $("#existing-view-stuff") }); var manager = new Backbone.Marionette.Region({ el: "#content", currentView: myView }); \`\`\` Call ``attachView`` On Region ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \`\`\`js MyApp.addRegions({ someRegion: "#content" }); var myView = new MyView({ el: $("#existing-view-stuff") }); MyApp.someRegion.attachView(myView); \`\`\` Region Events And Callbacks --------------------------- A region manager will raise a few events during it's showing and closing of views: - "show" / ``onShow`` - called on the view instance when the view has been rendered and displayed - "show" / ``onShow`` - called on the region isntance when the view has been rendered and displayed - "close" / ``onClose`` - when the view has been closed You can bind to these events and add code that needs to run with your region manager, opening and closing views. \`\```js MyApp.mainRegion.on("show", function(view){ // manipulate the``view``or do something extra // with the region manager via``this\` }); MyApp.mainRegion.on("closed", function(view){ // manipulate the ``view`` or do something extra // with the region manager via ``this`` }); MyRegion = Backbone.Marionette.Region.extend({ // ... onShow: function(view){ // the ``view`` has been shown } }); MyView = Marionette.ItemView.extend({ onShow: function(){ // called when the view has been shown } }); \`\`\` View Callbacks And Events For Regions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The region manager will call an ``onShow`` method on the view that was displayed. It will also trigger a "show" event from the view: \`\`\`js MyView = Backbone.View.extend({ onShow: function(){ // the view has been shown } }); view = new MyView(); view.on("show", function(){ // the view has been shown. }); MyApp.mainRegion.show(view); \`\`\` Custom Region Types ------------------- You can define a custom region manager by extending from ``Region``. This allows you to create new functionality, or provide a base set of functionality for your app. Attaching Custom Region Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once you define a region manager type, you can attach the new region type by specifying the region type as the value - not an instance of it, but the actual constructor function. \`\`\`js var FooterRegion = Backbone.Marionette.Region.extend({ el: "#footer" }); MyApp.addRegions({ footerRegion: FooterRegion }); \`\`\` You can also specify a selector for the region by using an object literal for the configuration. \`\`\`js var FooterRegion = Backbone.Marionette.Region.extend({ el: "#footer" }); MyApp.addRegions({ footerRegion: { selector: "#footer", type: FooterRegion } }); \`\`\` Note that a region must have an element to attach itself to. If you do not specify a selector when attaching the region instance to your Application or Layout, the region must provide an ``el`` either in it's definition or constructor options. Instantiate Your Own Region ~~~~~~~~~~~~~~~~~~~~~~~~~~~ There may be times when you want to add a region manager to your application after your app is up and running. To do this, you'll need to extend from ``Region`` as shown above and then use that constructor function on your own: \`\`\`js var SomeRegion = Backbone.Marionette.Region.extend({ el: "#some-div", initialize: function(options){ // your init code, here } }); MyApp.someRegion = new SomeRegion(); MyApp.someRegion.show(someView); \`\`\` You can optionally add an ``initialize`` function to your Region definition as shown in this example. It receives the ``options`` that were passed to the constructor of the Region, similar to a Backbone.View.