Регион Marionette

Регионы предоставляют согласованные методы для управления, отображения и уничтожения представлений в ваших приложениях и макетах. Они используют селектор jQuery для отображения ваших представлений в нужном месте.

Используя класс LayoutView, вы можете создавать вложенные регионы.

Индекс документации

Определение региона приложения
- Типы конфигурации регионов
Инициализация региона с el
Основное использование
Отображение представления
Проверка, отображает ли регион представление
reset Регион
Указание способа прикрепления el представления
Прикрепление существующего представления
- Установить currentView при инициализации
- Вызов attachView в регионе
События и обратные вызовы региона
Настраиваемые классы регионов
- Прикрепление настраиваемых классов регионов
- Инициализация собственного региона

Определение региона приложения

Вы можете добавить регионы в свои приложения, вызвав метод addRegions на экземпляре приложения. Этот метод ожидает единственный параметр в виде словаря, содержащего имена регионов и селекторы jQuery или объекты Region. Вы можете вызывать этот метод сколько угодно раз, и он будет продолжать добавлять регионы к приложению.

MyApp.addRegions({
  mainRegion: "#main-content",
  navigationRegion: "#navigation"
});

Как только вы вызовете addRegions, ваши регионы будут доступны в объекте приложения. В приведенном выше примере MyApp.mainRegion и MyApp.navigationRegion будут доступны для использования сразу же.

Если вы укажете одно и то же имя региона дважды, последнее из них будет использоваться.

Вы также можете добавить регионы через LayoutView:

var AppLayoutView = Marionette.LayoutView.extend({
  template: "#layout-view-template",

  regions: {
    menu: "#menu",
    content: "#content"
  }
});
var layoutView = new AppLayoutView();
layoutView.render();
// you can access your region by its name
layoutView.menu.show(new MenuView());
// also with the getRegion method
layoutView.getRegion('menu').show(new MenuView());
// or in this case reference and show it with the showChildView method
layoutView.showChildView('content', new MainContentView())

Типы конфигурации регионов

Marionette поддерживает несколько способов определения регионов в вашем Application или LayoutView.

Строковый селектор

Вы можете использовать строковый селектор jQuery для определения регионов.

App.addRegions({
  mainRegion: '#main'
});

Класс региона

Если вы создали настраиваемый класс региона, вы можете использовать его для определения своего региона.

ПРИМЕЧАНИЕ: Убедитесь, что свойство el класса региона установлено, иначе он не будет работать!

var MyRegion = Marionette.Region.extend({
  el: '#main-nav'
});

App.addRegions({
  navigationRegion: MyRegion
});

Литерал объекта

Наконец, вы можете определить регионы с помощью литерала объекта. Определения литералов объекта обычно ожидают свойство selector или el. Свойство selector — это строка-селектор, а свойство el может быть строкой-селектором, объектом jQuery или узлом HTML.

Вы также можете указать свойство regionClass для настраиваемого класса региона. Если ваш regionClass уже имеет свойство el , то вам не нужно указывать свойство selector или el в литерале объекта.

Любые другие свойства, которые вы зададите в литерале объекта, будут использоваться в качестве параметров, передаваемых экземпляру региона, включая параметр allowMissingEl.

Обычно регионы требуют наличия базового элемента DOM. В некоторых случаях может потребоваться разрешить создание и использование регионов без элемента, например, когда регионы, определенные классом родительского LayoutView класса, используются только некоторыми из его подклассов. В этих случаях регион можно определить с параметром allowMissingEl, чтобы подавить ошибку отсутствия элемента и обработать вызовы show региона как пустые операции.

var MyRegion      = Marionette.Region.extend();
var MyOtherRegion = Marionette.Region.extend();
var MyElRegion    = Marionette.Region.extend({ el: '#footer' });

App.addRegions({
  contentRegion: {
    el: '#content',
    regionClass: MyRegion
  },

  navigationRegion: {
    el: '#navigation',
    regionClass: MyOtherRegion,

    // Options passed to instance of `MyOtherRegion` for
    // the `navigationRegion` on `App`
    navigationOption: 42,
    anotherNavigationOption: 'foo'
  },

  footerRegion: {
    regionClass: MyElRegion
  }
});

Обратите внимание, что одним из основных преимуществ использования regionClass с уже заданным el является предоставление параметров экземпляру региона. Это невозможно при прямом использовании класса региона, как в предыдущих примерах.

var MyRegion = Marionette.Region.extend({
  el: '#content',
});

App.addRegions({
  contentRegion: {
    regionClass: MyRegion,
    myRegionOption: 'bar',
    myOtherRegionOption: 'baz'
  }
});

Смешанные типы

Конечно, вы можете смешивать типы конфигурации регионов.

var MyRegion = Marionette.Region.extend({
  el: '#content'
});

var MyOtherRegion = Marionette.Region.extend();

App.addRegions({
  contentRegion: MyRegion,

  navigationRegion: '#navigation',

  footerRegion: {
    el: '#footer',
    regionClass: MyOtherRegion
  }
});

Инициализация региона с `el`

Вы можете указать el для управления регионом во время инициализации региона:

var mgr = new Marionette.Region({
  el: "#someElement"
});

Параметр el также может быть ссылкой на сырой узел DOM:

var mgr = new Marionette.Region({
  el: document.querySelector("body")
});

Или el может быть узлом DOM, обернутым в jQuery:

var mgr = new Marionette.Region({
  el: $("body")
});

Основное использование

Отображение представления

После определения региона вы можете вызвать его методы show и empty для отображения и закрытия представления:

var myView = new MyView();

// render and display the view
MyApp.getRegion('mainRegion').show(myView, options);


// empties the current view
MyApp.getRegion('mainRegion').empty();

Объект options необязателен. Если он указан, он будет передан в события, сгенерированные во время show (кроме before:empty и empty). Особые свойства, меняющие поведение show, включают preventDestroy и forceShow.

preventDestroy

Если вы замените текущее представление новым, вызвав show, по умолчанию предыдущее представление будет автоматически уничтожено. Вы можете предотвратить это поведение, передав {preventDestroy: true} в параметре options. Несколько событий также будут сгенерированы в представлениях; подробнее см. раздел «События и обратные вызовы региона».

// Show the first view.
var myView = new MyView();
MyApp.getRegion('mainRegion').show(myView);

// Replace the view with another. The
// `destroy` method is called for you
var anotherView = new AnotherView();
MyApp.getRegion('mainRegion').show(anotherView);

// Replace the view with another.
// Prevent `destroy` from being called
var anotherView2 = new AnotherView();
MyApp.getRegion('mainRegion').show(anotherView2, { preventDestroy: true });

ПРИМЕЧАНИЕ. При использовании preventDestroy: true необходимо позаботиться об очистке старых представлений вручную, чтобы предотвратить утечки памяти.

forceShow

Если вы повторно вызовете show с тем же представлением, по умолчанию ничего не произойдёт, так как представление уже находится в регионе. Вы можете принудительно повторно отобразить представление, передав {forceShow: true} в параметре options.

var myView = new MyView();
MyApp.getRegion('mainRegion').show(myView);

// the second show call will re-show the view
MyApp.getRegion('mainRegion').show(myView, {forceShow: true});

Очистка региона

Вы можете очистить регион от его представления и содержимого, вызвав .empty() на экземпляре региона. Если вы хотите предотвратить уничтожение текущего представления в регионе, вы можете передать {preventDestroy: true} методу empty для предотвращения стандартного поведения уничтожения. Метод empty возвращает экземпляр региона после вызова.

onBeforeAttach & onAttach

Регионы, которые прикрепляются к документу при выполнении show, являются особыми, так как представления, которые они отображают, также будут прикреплены к документу. Эти регионы генерируют пару триггерных методов для *всех* представлений, которые должны быть прикреплены — даже вложенных. Это может вызвать проблему производительности, если вы отображаете сотни или тысячи представлений одновременно.

Если вы считаете, что эти события могут замедляют ваше приложение, вы можете выборочно отключить их с помощью свойств triggerBeforeAttach и triggerAttach или параметров show().

// No longer trigger attach
myRegion.triggerAttach = false;

Вы можете переопределить это на основе каждого отдельного отображения, передав его в качестве параметра в отображении.

// This region won't trigger beforeAttach...
myRegion.triggerBeforeAttach = false;

// Unless we tell it to
myRegion.show(myView, {triggerBeforeAttach: true});

Или вы можете оставить события включёнными по умолчанию, но отключить их для одного отображения.

// This region will trigger attach events by default but not for this particular show.
myRegion.show(myView, {triggerBeforeAttach: false, triggerAttach: false});

Проверка, отображает ли регион представление

Если вам нужно проверить, имеет ли регион представление, вы можете использовать функцию hasView. Она вернет булево значение в зависимости от того, отображает ли регион представление.

`reset` Регион

Регион может быть reset в любое время. Это уничтожает любое существующее отображаемое представление и удаляет кэшированный el. В следующий раз, когда регион отобразит представление, el региона будет запрошен из DOM.

myRegion.reset();

Это полезно, когда регионы повторно используются в разных экземплярах представлений и в тестировании.

Указание способа прикрепления `el` представления

Переопределите метод attachHtml региона, чтобы изменить способ прикрепления представления к DOM. Этот метод получает один параметр — представление, которое нужно отобразить.

Стандартная реализация attachHtml выглядит так:

Marionette.Region.prototype.attachHtml = function(view){
  this.$el.empty().append(view.el);
}

Это заменяет содержимое региона на el / содержимое представления. Вы можете переопределить attachHtml для эффектов перехода и большего.

Marionette.Region.prototype.attachHtml = function(view){
  this.$el.hide();
  this.$el.html(view.el);
  this.$el.slideDown("fast");
}

Также можно определить настраиваемый метод рендеринга для отдельного региона, расширив класс Region и добавив настраиваемый метод attachHtml.

Этот пример сделает представление скользить снизу вверх по экрану, а не просто появится на месте:

var ModalRegion = Marionette.Region.extend({
  attachHtml: function(view){
    // Some effect to show the view:
    this.$el.empty().append(view.el);
    this.$el.hide().slideDown('fast');
  }
})

MyApp.addRegions({
  mainRegion: '#main-region',
  modalRegion: {
    regionClass: ModalRegion,
    selector: '#modal-region'
  }
})

Если вы заинтересованы в анимациях регионов и ищете более производительное и продвинутое решение, ознакомьтесь с marionette-animated-region.

Прикрепление существующего представления

В некоторых сценариях желательно прикрепить существующее представление к региону без рендеринга или отображения представления и без замены содержимого HTML региона. Например, SEO и доступность часто требуют, чтобы HTML генерировался на сервере, и постепенного улучшения HTML.

Существует два способа достижения этого:

установить currentView в конструкторе региона
вызвать attachView на экземпляре региона

Установить `currentView` при инициализации

var myView = new MyView({
  el: $("#existing-view-stuff")
});

var region = new Marionette.Region({
  el: "#content",
  currentView: myView
});

Вызвать `attachView` в регионе

MyApp.addRegions({
  someRegion: "#content"
});

var myView = new MyView({
  el: $("#existing-view-stuff")
});

MyApp.getRegion('someRegion').attachView(myView);

События и обратные вызовы региона

Регион будет генерировать несколько событий на себе и на целевом представлении при отображении и уничтожении представлений.

События, возникающие в регионе во время `show()`

before:show / onBeforeShow - Вызывается после того, как представление было обработано, но перед его отображением.
show / onShow - Вызывается, когда представление было обработано и отображено.
before:swap / onBeforeSwap - Вызывается перед отображением нового представления. ПРИМЕЧАНИЕ: это будет вызвано только при замене представления, а не когда регион пустой.
swap / onSwap - Вызывается при отображении нового представления. ПРИМЕЧАНИЕ: это будет вызвано только при замене представления, а не когда регион пустой.
before:swapOut / onBeforeSwapOut - Вызывается перед заменой представления. ПРИМЕЧАНИЕ: это будет вызвано только при замене представления, а не когда регион пустой.
swapOut / onSwapOut - Вызывается при замене нового представления, которое должно заменить текущее показанное представление. ПРИМЕЧАНИЕ: это будет вызвано только при замене представления, а не когда регион пустой.
before:empty / onBeforeEmpty - Вызывается перед удалением представления.
empty / onEmpty - Вызывается после удаления представления.

События, возникающие в представлении во время `show()`

before:render / onBeforeRender - Вызывается перед отрисовкой представления.
render / onRender - Вызывается после отрисовки представления, но перед прикреплением его к DOM.
before:show / onBeforeShow - Вызывается после отрисовки представления, но перед привязкой его к области.
before:attach / onBeforeAttach - Вызывается перед прикреплением представления к DOM. Это не будет вызываться, если сама область не прикреплена.
attach / onAttach - Вызывается после прикрепления представления к DOM. Это не будет вызываться, если сама область не прикреплена.
show / onShow - Вызывается, когда представление было отрисовано и привязано к области.
dom:refresh / onDomRefresh - Вызывается, когда представление было отрисовано и отображено, но только если оно прикреплено к DOM. Это не будет вызываться, если сама область не прикреплена.
before:destroy / onBeforeDestroy - Вызывается перед уничтожением представления.
destroy / onDestroy - Вызывается после уничтожения представления.

Примечание: render, destroy, и dom:refresh вызываются для чистых представлений Backbone во время отображения, но для полной реализации этих событий представление Backbone должно вызывать render внутри render() и destroy внутри remove(), а также устанавливать следующие флаги:

view.supportsRenderLifecycle = true;
view.supportsDestroyLifecycle = true;

Обработчики событий

MyApp.getRegion('mainRegion').on("before:show", function(view, region, options){
  // manipulate the `view` or do something extra
  // with the `region`
  // you also have access to the `options` that were passed to the Region.show call
});

MyApp.getRegion('mainRegion').on("show", function(view, region, options){
  // manipulate the `view` or do something extra
  // with the `region`
  // you also have access to the `options` that were passed to the Region.show call
});

MyApp.getRegion('mainRegion').on("before:swap", function(view, region, options){
  // manipulate the `view` or do something extra
  // with the `region`
  // you also have access to the `options` that were passed to the Region.show call
});

MyApp.getRegion('mainRegion').on("swap", function(view, region, options){
  // manipulate the `view` or do something extra
  // with the `region`
  // you also have access to the `options` that were passed to the Region.show call
});

MyApp.getRegion('mainRegion').on("before:swapOut", function(view, region, options){
  // manipulate the `view` or do something extra
  // with the `region`
  // you also have access to the `options` that were passed to the Region.show call
});

MyApp.getRegion('mainRegion').on("swapOut", function(view, region, options){
  // manipulate the `view` or do something extra
  // with the `region`
  // you also have access to the `options` that were passed to the Region.show call
});

MyApp.getRegion('mainRegion').on("empty", function(view, region){
  // manipulate the `view` or do something extra
  // with the `region`
});

var MyRegion = Marionette.Region.extend({
  // ...

  onBeforeShow: function(view, region, options) {
    // the `view` has not been shown yet
  },

  onShow: function(view, region, options){
    // the `view` has been shown
  }
});

var MyView = Marionette.ItemView.extend({
  onBeforeShow: function(view, region, options) {
    // called before the `view` has been shown
  },
  onShow: function(view, region, options){
    // called when the `view` has been shown
  }
});

var MyRegion = Marionette.Region.extend({
  // ...

  onBeforeSwap: function(view, region, options) {
    // the `view` has not been swapped yet
  },

  onSwap: function(view, region, options){
    // the `view` has been swapped
  },

  onBeforeSwapOut: function(view, region, options) {
    // the `view` has not been swapped out yet
  },

  onSwapOut: function(view, region, options){
    // the `view` has been swapped out
  }
});

Настраиваемые классы областей

Вы можете определить настраиваемую область, расширив класс Region. Это позволяет вам создавать новую функциональность или предоставлять базовый набор функциональности для вашего приложения.

Прикрепление настраиваемых классов областей

После определения класса области вы можете прикрепить новый класс области, указав класс области как значение. В этом случае addRegions ожидает сам конструктор, а не экземпляр.

var FooterRegion = Marionette.Region.extend({
  el: "#footer"
});

MyApp.addRegions({
  footerRegion: FooterRegion
});

Вы также можете указать селектор для области, используя литерал объекта для конфигурации.

var FooterRegion = Marionette.Region.extend({
  el: "#footer"
});

MyApp.addRegions({
  footerRegion: {
    selector: "#footer",
    regionClass: FooterRegion
  }
});

Обратите внимание, что область должна иметь элемент, к которому она может прикрепиться. Если вы не указываете селектор при прикреплении экземпляра области к вашему приложению или представлению макета, область должна предоставить el либо в своём определении, либо в опциях конструктора.

Создание собственной области

Возможно, вам нужно будет добавить область к вашему приложению после запуска приложения. Для этого вам нужно расширить класс Region как показано выше, а затем использовать эту конструкторскую функцию самостоятельно:

var SomeRegion = Marionette.Region.extend({
  el: "#some-div",

  initialize: function(options){
    // your init code, here
  }
});

MyApp.someRegion = new SomeRegion();

MyApp.getRegion('someRegion').show(someView, options);

Вы можете по желанию добавить функцию initialize в определение вашей области, как показано в этом примере. Она получает options , которые были переданы в конструктор области, аналогично Backbone.View.