regions-extras

Extra regions for marionette

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
regions-extras
1004.0.27 years ago10 years agoMinified + gzip package size for regions-extras in KB

Readme

Regions extras Build Status
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
v1.1.0
BC: Async regions expect View.promise method. Early was then method.

v1.0.6

Auto load replace region to avoid BC

v1.0.5

Add region manager Add async, regionType options Add AsyncReplaceRegion

v1.0.4

Add regionClass option

v1.0.3

#4 Can't use region for second time Karma + jasmine specs

v1.0.2

Pass view option through helper

v1.0.1

tag and tagName option to setup tagName
v1.0.0
Marionette 2.0