Регионы

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

См. документацию по выстраиванию представлений для введения в управление регионами в рамках вашего приложения.

Регион — это Marionette.Object и имеет весь его функционал.

Регионы поддерживают жизненный цикл представления при отображении или очистке представления.

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

Определение региона приложения
Определение регионов
Добавление регионов
Удаление регионов
Использование регионов в представлении
Отображение представления
- Проверка, отображает ли регион представление
- Представления, не являющиеся Marionette
  - Частично рендеренные представления
Отображение шаблона
Очистка региона
- Сохранение существующих представлений
- Отсоединение существующих представлений
reset Регион
Проверка, меняется ли представление другим
Настройка способа прикрепления элемента представления
Настройка способа удаления представления

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

Приложение определяет один регион el с помощью атрибута region. К нему можно получить доступ через getRegion() или напрямую отобразить представление с помощью showView(). Ниже приведен короткий пример:

var Mn = require('backbone.marionette');
var SomeView = require('./view');

var App = Mn.Application.extend({
  region: '#main-content',

  onStart: function() {
    var main = this.getRegion();  // Has all the properties of a `Region`
    main.show(new SomeView());
  }
});

Дополнительную информацию см. в документации по приложениям.

Определение регионов

Marionette поддерживает несколько способов определения регионов в вашем Application или View. Этот раздел документирует различные типы, применяемые к View, хотя они также будут работать для Application - просто замените regions на region в вашем определении.

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

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

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  regions: {
    mainRegion: '#main'
  }
});

Дополнительные параметры

Вы можете определять регионы с помощью объекта-литерала. Определения объекта-литерала ожидают свойство el — строковый селектор jQuery для подключения региона. Определение с помощью объекта-литерала — наиболее распространенный способ определения того, перезаписывает ли отображение региона родительский el или просто перезаписывает содержимое (по умолчанию).

Чтобы перезаписать родительский el региона содержимым рендеренного внутреннего представления, используйте replaceElement следующим образом:

var Mn = require('backbone.marionette');

var OverWriteView = Mn.View.extend({
  className: '.new-class'
});

var MyView = Mn.View.extend({
  regions: {
    main: {
      el: '.overwrite-me',
      replaceElement: true
    }
  }
});
var view = new MyView();
view.render();

console.log(view.$('.overwrite-me').length); // 1
console.log(view.$('.new-class').length); // 0

view.showChildView('main', new OverWriteView());

console.log(view.$('.overwrite-me').length); // 0
console.log(view.$('.new-class').length); // 1

При рендеринге экземпляра MyView элемент .overwrite-me будет удален из DOM и заменён элементом .new-class — это позволяет нам легче отображать представления внутри table или select, — эти элементы обычно очень строго относятся к тому, какое содержимое они позволят.

УСТАНОВЛЕНО: Параметр selector региона устарел в пользу использования el

var MyView = Mn.View.extend({
  regions: {
    deprecatedRegionDefinition: {
      selector: '.foo',
      replaceElement: true
    },
    regionDefinition: {
      el: '.bar',
      replaceElement: true
    }
  }
});

Указание регионов как функции

Атрибут regions в представлении может быть функцией, возвращающей объект:

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  regions: function(){
    return {
      firstRegion: '#first-region'
    };
  }
});

Использование класса RegionClass

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

var Mn = require('backbone.marionette');

var MyRegion = Mn.Region.extend({
  onShow: function(){
    // Scroll to the middle
    this.$el.scrollTop(this.currentView.$el.height() / 2 - this.$el.height() / 2);
  }
});

var MyView = Mn.View.extend({
  regions: {
    firstRegion: {
      el: '#first-region',
      regionClass: MyRegion
    }
  }
});

Пример в реальном времени

Ссылка на пользовательский интерфейс в `regions`

Атрибут UI может быть полезен при установке селекторов региона — просто используйте префикс @ui.:

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  ui: {
    region: '#first-region'
  },
  regions: {
    firstRegion: '@ui.region'
  }
});

Пример в реальном времени

Добавление регионов

Чтобы добавить регионы в представление после его создания, просто используйте метод addRegion:

var MyView = require('./myview');

myView = new MyView();
myView.addRegion('thirdRegion', '#third-region');

Теперь мы можем получить доступ к thirdRegion так же, как и к другим.

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

var MyView = require('./myview');

myView = new MyView();
myView.addRegions({
  main: {
    el: '.overwrite-me',
    replaceElement: true
  },
  sidebar: '.sidebar'
});

Удаление регионов

Вы можете удалить все регионы из представления, вызвав removeRegions, или вы можете удалить регион по имени, используя removeRegion. При удалении региона он будет уничтожен.

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  regions: {
    main: '.main',
    sidebar: '.sidebar',
    header: '.header'
  }
});

var myView = new MyView();

// remove only the main region
var mainRegion = myView.removeRegion('main');

mainRegion.isDestroyed(); // -> true

// remove all regions
myView.removeRegions();

Использование регионов в представлении

В дополнение к добавлению и удалению регионов есть несколько методов, которые помогут использовать регионы.

getRegion(name) — запрос региона из представления по имени.
- Примечание: если представление ещё не отрисовано, оно будет отрисовано.
getRegions() — возвращает объект-литерал всех регионов в представлении, организованных по имени.
- Примечание: если представление ещё не отрисовано, оно будет отрисовано.
hasRegion(name) — проверка наличия региона в представлении.
emptyRegions() — очистка всех регионов в представлении.

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

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

var myView = new MyView();
var childView = new MyChildView();
var mainRegion = myView.getRegion('main');

// render and display the view
mainRegion.show(childView);

Это эквивалентно методу showChildView представления, который можно использовать следующим образом:

var myView = new MyView();
var childView = new MyChildView();

// render and display the view
myView.showChildView('main', childView);

Оба варианта принимают объект options, который будет передан событиям, которые генерируются при show.

Дополнительную информацию о showChildView и getChildView, см. в документации по представлениям

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

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

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

mainRegion.hasView() // false
mainRegion.show(new OtherView());
mainRegion.hasView() // true

Если вы отображаете представление в регионе с существующим представлением, Marionette удалит существующее представление перед отображением нового.

Представления, не являющиеся Marionette

Регионы Marionette не предназначены только для отображения представлений Marionette — они также могут отображать экземпляры обычных Backbone.View. Для этого убедитесь, что ваше представление определяет метод render() и просто используйте его как обычное представление Marionette:

var Bb = require('backbone');
var Mn = require('backbone.marionette');
var _ = require('underscore');

var MyChildView = Bb.View.extend({
  render: function() {
    this.$el.append('<p>Some text</p>');
  },

  onRender: function() {
    console.log('Regions also fire Lifecycle events on Backbone.View!');
  }
});

var MyParentView = Mn.View.extend({
  regions: {
    child: '.child-view'
  },

  template: _.template('<div class="child-view"></div>'),

  onRender: function() {
    this.showChildView('child', new MyChildView());
  }
});

Как вы можете видеть выше, вы можете прослушивать события жизненного цикла на Backbone.View и Marionette будет генерировать события для вас.

Частично рендеренные представления

Некоторые библиотеки частично "отрендерят" представление, установив свой $el. Это может вызвать проблемы с Marionette, предполагающим, что оно уже отрендерено. Чтобы обойти это, нужно вручную вызвать render перед отображением представления:

var MyParentView = Mn.View.extend({
  regions: {
    child: '.child-view'
  },

  template: _.template('<div class="child-view"></div>'),

  onRender: function() {
    var backgridView = new BackgridView({collection: myCollection});
    backgridView.render();
    this.showChildView('child', backgridView);
  }
});

Библиотеки, которые известны таким поведением:

Backgrid 0.3.7

Это поведение является частью Marionette.View#setElement().

Отображение шаблона

Вы можете отобразить шаблон или строку напрямую в регион. Кроме того, вы можете передать объект-литерал, содержащий шаблон и любые другие параметры представления. Под капотом создаётся экземпляр Marionette.View с использованием шаблона.

var myView = new MyView();

var template = _.template('This is the <%- section %> page');
var templateContext = templateContext: { section: 'main' };

myView.showChildView('main', {
  template: template,
  templateContext: templateContext
});

myView.showChildView('header', _.template('Welcome to the site'));

myView.getRegion('other').show('This text is in another region');

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

Вы можете удалить представление из региона (эффективно "скрыть" его) с помощью region.empty() в регионе:

var myView = new MyView();

myView.showChildView('main', new OtherView());
var mainRegion = myView.getRegion('main');
mainRegion.empty();

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

Примечание: если регион не содержит представления, при очистке он будет отсоединять любой HTML внутри региона. Если регион содержит представление, любой HTML, который не принадлежит представлению, останется.

Сохранение существующих представлений

УСТАНОВЛЕНО: preventDestroy устарел. См. Отсоединение существующих представлений для получения информации о сохранении отображенного представления

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

// Show the first view.
var myView = new MyView();
var childView = new MyChildView();

var mainRegion = myView.getRegion('main');

mainRegion.show(childView);

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

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

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

Отсоединение существующих представлений

Если вы хотите отсоединить существующее представление от региона, используйте detachView.

var myView = new MyView();

var myOtherView = new MyView();

var childView = new MyChildView();

// render and display the view
myView.showChildView('main', childView);

// ... somewhere down the line
myOtherView.showChildView('main', myView.getRegion('main').detachView());

`reset` Регион

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

var myView = new MyView();
myView.showChildView('main', new OtherView());
var mainRegion = myView.getRegion('main');
myRegion.reset();

Это может быть полезно при тестировании представлений.

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

Метод isSwappingView возвращает значение, указывающее, заменяется ли представление другим. Это полезно внутри событий/методов жизненного цикла региона.

Пример покажет сообщение, когда регион пуст:

var Mn = require('backbone.marionette');

var EmptyMsgRegion = Mn.Region.extend({
  onEmpty() {
    if (!this.isSwappingView()) {
      this.$el.append('Empty Region');
    }
  }
});

Пример в реальном времени

Настройка способа прикрепления элемента представления

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

Стандартная реализация метода attachHtml по сути:

var Mn = require('backbone.marionette');

Mn.Region.prototype.attachHtml = function(view){
  this.el.appendChild(view.el);
}

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

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

var Mn = require('backbone.marionette');

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

var MyView = Mn.View.extend({
  regions: {
    mainRegion: '#main-region',
    modalRegion: {
      regionClass: ModalRegion,
      el: '#modal-region'
    }
  }
});

Настройка способа удаления представления

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

Стандартная реализация removeView:

var Mn = require('backbone.marionette');

Mn.Region.prototype.removeView = function(view){
  this.destroyView(view);
}

Метод destroyView уничтожает представление, учитывая, является ли оно потомком Marionette.View или обычным представлением Backbone. Он может быть заменён вызовом view.destroy(), если гарантировано, что представление происходит от Marionette.View

В этом примере будет использоваться эффект плавного перехода при отображении и скрытии представления:

var Mn = require('backbone.marionette');

var AnimatedRegion = Mn.Region.extend({
  attachHtml(view) {
    view.$el
      .css({display: 'none'})
      .appendTo(this.$el);
    if (!this.isSwappingView()) view.$el.fadeIn('slow');
  },

  removeView(view) {
    var self = this;
    view.$el.fadeOut('slow', function() {
      self.destroyView(view);
      if (self.currentView) self.currentView.$el.fadeIn('slow');
    });
  }
});

var MyView = Mn.View.extend({
  regions: {
    animatedRegion: {
      regionClass: AnimatedRegion,
      el: '#animated-region'
    }
  }
});

Пример в реальном времени

Используя аналогичный подход, можно создать область с анимацией с помощью CSS:

Пример в реальном времени

Регионы

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

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

Определение регионов

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

Дополнительные параметры

Указание регионов как функции

Использование класса RegionClass

Ссылка на пользовательский интерфейс в regions

Добавление регионов

Удаление регионов

Использование регионов в представлении

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

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

Представления, не являющиеся Marionette

Частично рендеренные представления

Отображение шаблона

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

Сохранение существующих представлений

Отсоединение существующих представлений

reset Регион

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

Настройка способа прикрепления элемента представления

Настройка способа удаления представления

Ссылка на пользовательский интерфейс в `regions`

`reset` Регион