Regions-extras NPM

Regions extras

Extra regions for marionette.

Install helper to system

npm install --save regions-extras

and now register in Handlebars

import 'regions-extras';

Replace region

Allow you specify region as placeholder to replace with real view dom element.

For example we have this template:

<body>
    <div id="region"></div>
</body>

and this script:

var ReplaceRegion = require('regions-extras/lib/ReplaceRegion');
var region = new ReplaceRegion({
    el: '#region'
});

region.show(new SomeList({
    tagName: 'ul'
});

the result wil be:

<body>
    <ul>
        <!-- some code that generate view -->
    </ul>
</body>

It is register in region manager as replace.

Async replace region

This region work like replace region, but it delay view render. Region expect implemented promise method in view, which return promise (jQuery.Deferred or Promise for example). View will be rendered when promise fulfilled.

var AsyncReplaceRegion = require('regions-extras/lib/AsyncReplaceRegion');
var AsyncView = Backbone.View.extend({
    promise: function () {
        return this.model.fetch();
    }
});

var region = new AsyncReplaceRegion({
    el: '#region'
});
    
region.show(new SomeList({
    model: new User({id: 12})
});

It is registered in region manager as async_replace.

Another way of working with the AsyncReplaceRegion is providing a custom promise to it. After resolving a promise the AsyncReplaceRegion starts working the same as the ReplaceRegion.

var AsyncReplaceRegion = require('regions-extras/lib/AsyncReplaceRegion');

var region = new AsyncReplaceRegion({
    el: '#region',
    promise: function() {
        return this.model.fetch(); 
    }
});
    
region.show(MyCustomView);

Region helper

Handlebars helper, which mark place for region and inject it to Marionette.Layout that use it.

For example:

<div class="some">

    {{region "test"}}

</div>

and Layout:

require('region-extras');

var Layout = Marionette.View.extend({
     template: require('./tpl/template.hbs'),

     onRender: function () {
         this.test.show(new SomeView()); // region 'test' will be appeared here automatic
     }
 });

It is use replace region by default for now.

Additionally, region helper allow you override some useful options:

tagName

{{region tagName="ul"}} -> <ul id="region123"></ul>

regionClass

You can specify class of region to create

{{region "test" regionClass=YOUR_REGION_CLASS}}

regionType

It is like regionClass option, but use region manager to create region

in js

var manager = require('regions-extras/lib/RegionManager').defaultManager;
manager.addRegion('my_region', SomeRegionClass);

and in template

{{region "test" regionType="my_region"}}

If you require builtin regions (ReplaceRegion or AsyncReplaceRegion) we register it for you

{{region "test" regionType="replace"}} ## By default
{{region "test" regionType="async_replace"}}

async

This option is sugar for regionType option. It is append async_ prefix to regionType

{{region "test" async=true}}

is equal to

{{region "test" regionType="async_replace"}}

promise

This option is optional and is used for resolving async region to start showing views in it. If not provided, the view.promise() method will be invoked instead every time you call the region.show() method.

{{region "test" async=true promise=myCustomPromise}}

Changelog

v4.0.0

Marionette 3

v3.0.0

Async regions use native Promise internally instead of jQuery.Deferred

v2.1.1

Add _parent link to every view which attach to region, to unify method of parent search

v2.1.0

All regions now have link to parent in _parentView
Use $el instead of el when possible
More strong replacement in replace region

V2.0.0

BC: API change. Helper register now looks like:

require('regions-extras').register({
    Handlebars: require('injectify/runtime'),
    Marionette: require('backbone.marionette')
});

BC: remove handlebars and marionette registry. Pass instances to register function
BC: remove replace-region file from root, use require('regions-extras/region/ReplaceRegion') instead