Менеджер областей Marionette.RegionManager

Менеджеры областей предоставляют согласованный способ управления несколькими объектами Marionette.Region в приложении. Менеджер областей предназначен для использования другими объектами для облегчения добавления, хранения, извлечения и удаления областей из этого объекта. Примеры использования см. в объектах Marionette.Application и Marionette.LayoutView.

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

• Базовое использование
• Создание
• RegionManager.addRegion
• RegionManager.addRegions
  • Параметры по умолчанию для addRegions
• RegionManager.get
• RegionManager.getRegions
• RegionManager.removeRegion
• RegionManager.removeRegions
• RegionManager.emptyRegions
• RegionManager.destroy
• События RegionManager
  • Событие before:add:region
  • Событие add:region
  • Событие before:remove:region
  • Событие remove:region
• Итераторы RegionManager

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

Менеджеры областей можно создавать напрямую и добавлять/удалять области с помощью нескольких методов:

var rm = new Marionette.RegionManager();

var region = rm.addRegion("foo", "#bar");

var regions = rm.addRegions({
  baz: "#baz",
  quux: "ul.quux"
});

regions.get('baz').show(myView, options);

rm.removeRegion("foo");

Создание

Менеджер областей принимает необязательный region параметр в конструкторе. Области передаются напрямую в addRegions для экземпляра менеджера областей.

var manager = new Marionette.RegionManager({
  regions: {
    "aRegion": "#bar"
  }
});

manager.get('aRegion').show(new MyView, options);

RegionManager.addRegion

Области можно добавлять индивидуально с помощью метода addRegion. Этот метод принимает два параметра: имя области и определение области.

var rm = new Marionette.RegionManager();

var region = rm.addRegion("foo", "#bar");

В этом примере область с именем "foo" будет добавлена к экземпляру RegionManager. Она определена как jQuery-селектор, который будет искать элемент #bar в DOM.

Существует множество других способов определения области, включая литералы объектов с различными параметрами и экземпляры объектов Region. Более подробную информацию см. в документации по Region.

RegionManager.addRegions

Области также можно добавлять оптом с помощью метода addRegions. Этот метод принимает литерал объекта или функцию, возвращающую литерал объекта. Литерал объекта должен содержать имена областей в качестве ключей и определения областей в качестве значений. Возвращаемое значение — литерал объекта со всеми созданными областями.

var rm = new Marionette.RegionManager();

// With an object literal
var regions = rm.addRegions({
  main: '#main-content',
  navigation: {
    selector: '#navigation',
    regionClass: MyNavRegion
  }
});

// With a function
var otherRegions = rm.addRegions(function(regionDefinition) {
  return {
    footer: '#footer'
  };
});

regions.get('main');        //=> 'main' region instance
regions.get('navigation');  //=> 'navigation' region instance
otherRegions.get('footer'); //=> 'footer' region instance

Если вы передадите функцию в addRegions, она будет вызвана с контекстом экземпляра RegionManager и всеми аргументами, переданными в addRegions.

var rm = new Marionette.RegionManager();

var regionDefaults = {
  regionClass: MyRegionClass
};

rm.addRegions(function(regionDefinition, defaults) {
  console.log(this);             // `rm` instance of `RegionManager`
  console.log(regionDefinition); // the region definition function
  console.log(defaults);         // `{ regionClass: MyRegionClass }`

  // ...return the region definiton object literal
}, regionDefaults);

Параметры по умолчанию для addRegions

При добавлении нескольких областей может быть полезно предоставить набор параметров по умолчанию, которые применяются ко всем добавляемым областям. Это можно сделать с помощью параметра defaults. Укажите этот параметр в виде литерала объекта со key: value парами, которые будут применяться к каждой добавляемой области.

var rm = new Marionette.RegionManager();

var defaults = {
  regionClass: MyRegionClass
};

var regions = {
  foo: "#bar",
  baz: "#quux"
};

rm.addRegions(regions, defaults);

В этом примере все области будут добавлены как экземпляры MyRegionClass.

RegionManager.get

Экземпляр области можно получить из экземпляра RegionManager, используя метод get и передав имя области.

var rm = new Marionette.RegionManager();
rm.addRegion("foo", "#bar");

var region = rm.get("foo");

RegionManager.getRegions

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

var rm = new Marionette.RegionManager();
rm.addRegion("foo", "#foo");
rm.addRegion("bar", "#bar");

var regions = rm.getRegions();

regions.foo; //=> foo region
regions.bar; //=> bar region

RegionManager.removeRegion

Область можно удалить, вызвав метод removeRegion и передав имя области.

var rm = new Marionette.RegionManager();
rm.addRegion("foo", "#bar");

rm.removeRegion("foo");

Перед удалением области из экземпляра RegionManager будет вызван её метод empty, и вызовется stopListening.

RegionManager.removeRegions

Вы можете быстро удалить все области из экземпляра RegionManager, вызвав метод removeRegions.

var rm = new Marionette.RegionManager();
rm.addRegions({
  foo: "#foo",
  bar: "#bar",
  baz: "#baz"
});

rm.removeRegions();

Это очистит все области и удалит их.

RegionManager.emptyRegions

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

var rm = new Marionette.RegionManager();
rm.addRegions({
  foo: "#foo",
  bar: "#bar",
  baz: "#baz"
});

rm.emptyRegions();

Это очистит области, не удаляя их из экземпляра RegionManager.

RegionManager.destroy

Экземпляр RegionManager можно полностью уничтожить, вызвав метод destroy. Это уничтожит и удалит все области из экземпляра RegionManager.

var rm = new Marionette.RegionManager();
rm.addRegions({
  foo: "#foo",
  bar: "#bar",
  baz: "#baz"
});

rm.destroy();

События RegionManager

При использовании RegionManager будут срабатывать различные события.

Событие before:add:region

При добавлении области в менеджер сработает событие "before:add:region". Это позволяет выполнить некоторые действия с областью до её добавления.

var rm = new Marionette.RegionManager();

rm.on("before:add:region", function(name, region){
  // do something with the region instance
});

rm.addRegion("foo", "#bar");

Событие add:region

Когда область добавляется в менеджер, RegionManager генерирует событие "add:region". Это позволяет вам использовать экземпляр области сразу или привязать его к объекту, нуждающемуся в ссылке на него:

var rm = new Marionette.RegionManager();

rm.on("add:region", function(name, region){
  // add the region instance to an object
  myObject[name] = region;
});

rm.addRegion("foo", "#bar");

Событие before:remove:region

Перед удалением области из менеджера сработает событие "before:remove:region". Это позволяет выполнить необходимые действия по очистке перед удалением области.

var rm = new Marionette.RegionManager();

rm.on("before:remove:region", function(name, region){
  // do something with the region instance here
});

rm.addRegion("foo", "#bar");

rm.removeRegion("foo");

Событие remove:region

Когда область удаляется из менеджера, RegionManager генерирует событие "remove:region". Это позволяет вам использовать экземпляр области один раз или удалить область из объекта, имеющего на неё ссылку:

var rm = new Marionette.RegionManager();

rm.on("remove:region", function(name, region){
  // add the region instance to an object
  delete myObject[name];
});

rm.addRegion("foo", "#bar");

rm.removeRegion("foo");

Итераторы RegionManager

У RegionManager есть несколько методов итерации, унаследованных от underscore.js. Это работает так же, как и методы Backbone.Collection, которые были импортированы. Например, вы можете легко перебрать весь набор экземпляров областей, вызвав метод each:

var rm = new Marionette.RegionManager();

rm.each(function(region){
  // do stuff w/ the region instance here
});

Список методов underscore включает:

• forEach
• each
• map
• find
• detect
• filter
• select
• reject
• every
• all
• some
• any
• include
• contains
• invoke
• toArray
• first
• initial
• rest
• last
• without
• isEmpty
• pluck