Функции Marionette

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

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

• Marionette.extend
• Marionette.isNodeAttached
• Marionette.mergeOptions
• Marionette.getOption
• Marionette.triggerMethod
• Marionette.triggerMethodOn
• Marionette.bindEvents
• Marionette.unbindEvents
• Marionette.bindRequests
• Marionette.unbindRequests
• Marionette.normalizeMethods
• Marionette.noConflict

Marionette.extend

Функция Backbone's extend является полезным инструментом и используется в различных местах в Marionette. Для повышения согласованности использования метод Backbone's extend был переименован в Marionette.extend. Это позволяет получить функциональность extend для вашего объекта, не определяя, хотите ли вы использовать Backbone.View или Backbone.Model или другой объект Backbone для получения метода.

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

var Foo = function(){};

// use Marionette.extend to make Foo extendable, just like other
// Backbone and Marionette objects
Foo.extend = Mn.extend;

// Now Foo can be extended to create a new class, with methods
var Bar = Foo.extend({

  someMethod: function(){ ... }

  // ...
});

// Create an instance of Bar
var b = new Bar();

Пример в браузере

Marionette.isNodeAttached

Определяет, является ли переданный узел потомком document или нет.

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

var div = document.createElement('div');
Mn.isNodeAttached(div);
// => false

$('body').append(div);
Mn.isNodeAttached(div);
// => true

Пример в браузере

Marionette.mergeOptions

Удобная функция для извлечения определенных options и прямого присоединения их к экземпляру. Все классы Marionette, такие как Views, имеют этот метод.

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

var options = {
  color: 'red',
  size: 'small',
  shape: 'square',
  weight: 'light'
}

var MyView = Mn.View.extend({
  myViewOptions: ['color', 'size', 'country'],

  initialize: function(options) {
    this.mergeOptions(options, this.myViewOptions);
  },

  onRender: function() {
    // The merged options will be attached directly to the prototype
    this.$el.addClass(this.color);
  }
});

var myView = new MyView(options);

Marionette.mergeOptions(myView, options, ['shape', 'weight']);

myView.getOption('color');   // red
myView.getOption('size');    // small
myView.getOption('country'); // undefined
myView.getOption('shape');   // square
myView.getOption('weight');  // light

Пример в браузере

Marionette.getOption

Получить атрибут объекта напрямую из объекта или из опций объекта this.options, с this.options имеющими приоритет. Все классы Marionette, такие как Views, имеют этот метод. this.getOption используется для экземпляра класса Marionette. Marionette.getOption используется для экземпляра класса Backbone.

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

var Obj = Mn.Object.extend({
  foo: 'bar',

  initialize: function(){
    var foo = this.getOption('foo');
    console.log(foo);
  }
});

var obj1 = new Obj(); // => 'bar'
var obj2 = new Obj({ foo: 'quux' }); // => 'quux'

Пример в браузере

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

var Model = Bb.Model.extend({
  foo: 'bar',

  initialize(attributes, options) {
    this.options = options;
    var foo = Mn.getOption(this, 'foo');
    console.log(foo);
  }
});

var model1 = new Model(); // => 'bar'
var model2 = new Model({}, { foo: 'quux' }); // => 'quux'

Пример в браузере

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

Ложные значения

Функция getOption вернёт любое ложное значение из options, кроме undefined. Если у объекта есть неопределенное значение в опциях, оно попытается прочитать значение непосредственно из объекта.

Например:

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

var Model = Bb.Model.extend({
  foo: 'bar',

  initialize: function(){
    var foo = Mn.getOption(this, 'foo');
    console.log(foo);
  }
});

var model1 = new Model(); // => "bar"

var foo;
var model2 = new Model({}, { foo: foo }); // => "bar"

Пример в браузере

В этом примере возвращается «bar» в обоих случаях, потому что во втором примере для f задано неопределённое значение.

Marionette.triggerMethod

Срабатывает событие и соответствующий метод в целевом объекте. Все классы Marionette, такие как Views, имеют этот метод.

Когда событие срабатывает, первая буква каждого раздела имени события капитализируется, и слово «on» добавляется перед ним. Примеры:

• triggerMethod('foo') вызывает функцию «onFoo»
• triggerMethod('before:foo') вызывает функцию «onBeforeFoo»

Все аргументы, которые передаются в вызов triggerMethod, передаются как в событие, так и в метод, за исключением имени события, которое не передаётся в соответствующий метод.

triggerMethod('foo', bar) вызовет onFoo: function(bar){...})

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

var MyObject = Mn.Object.extend({
  initialize: function(){
    this.triggerMethod('foo', 'baz');
  },
  onFoo: function(bar){
    console.log(bar);
  }
});

var myObj = new MyObject(); // console.log "baz"

Mn.triggerMethod(myObj, 'foo', 'qux'); // console.log "qux"

Примечание: Некоторые классы Marionette, такие как Views, переопределяют triggerMethod. Использование Mn.triggerMethod с просмотром нарушит делегирование событий. Если вам нужно выполнить triggerMethod на классе Marionette, рекомендуется использовать triggerMethodOn.

Marionette.triggerMethodOn

Вызвать triggerMethod в определённом контексте.

Это полезно, когда неясно, определён ли объект triggerMethod. В случае с просмотрами Marionette.View определяет triggerMethod, но Backbone.View нет.

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

Mn.triggerMethodOn(ctx, 'foo', bar);
// will invoke `onFoo: function(bar){...})`
// will trigger "foo" on ctx

Marionette.bindEvents

Этот метод используется для привязки «сущности» Backbone (например, коллекции/модели) к методам в целевом объекте. Это будет работать с любым классом, который работает с API Backbone.Events. Все классы Marionette, такие как Views, имеют этот метод.

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

var MyView = Bb.View.extend({

  modelEvents: {
    'change:foo': 'doSomething'
  },

  initialize: function(){
    Mn.bindEvents(this, this.model, this.modelEvents);
  },

  doSomething: function(){
    // the "change:foo" event was fired from the model
    // respond to it appropriately, here.
    this.trigger('something');
  }

});

var model = new Bb.Model();

var myView = new MyView({ model: model });

var MyObject = Mn.Object.extend({
  initialize: function() {
    this.bindEvents(myView, this.myEvents);
  },
  myEvents: {
    'something': 'onViewSomething'
  },
  onViewSomething: function() {
    console.log('view something');
  }
});

new MyObject();

model.set('foo')

Пример в браузере

Первый параметр, target, должен иметь модуль Backbone.Events.

Второй параметр — это entity (Backbone.Model, Backbone.Collection или любой объект, в который встроен Backbone.Events) для привязки событий.

Третий параметр — это хэш { 'event:name': 'eventHandler' } конфигурации. Вместо строкового имени обработчика можно передать функцию.

Примечание Многократные обработчики устарели

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

Marionette.unbindEvents

Этот метод можно использовать для отмены привязки обратных вызовов к событиям сущностей (например, коллекции/модели). Это противоположность bindEvents, описанной выше. Соответственно, API для каждого метода одинаковы. Все классы Marionette, такие как Views, имеют этот метод.

// Just like the above example we bind our model events.
// This time, however, we unbind them on close.
var Bb = require('backbone');
var Mn = require('backbone.marionette');

Bb.View.extend({

  modelEvents: {
    'change:foo': 'doSomething'
  },

  initialize: function(){
    Mn.bindEvents(this, this.model, this.modelEvents);
  },

  doSomething: function(){
    // the "change:foo" event was fired from the model
    // respond to it appropriately, here.
  },

  onClose: function() {
    Mn.unbindEvents(this, this.model, this.modelEvents);
  }

});

Пример в браузере

Marionette.bindRequests

Этот метод используется для привязки запросов радио к методам целевого объекта. Все объекты Marionette имеют этот метод.

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

var MyView = Mn.View.extend({
  channelName: 'myChannelName',

  radioRequests: {
    'foo:bar': 'fooBar'
  },

  initialize: function() {
    var channel = Radio.channel(this.channelName);
    Mn.bindRequests(this, channel, this.radioRequests);
  },

  fooBar: function() {
      console.log('foo:bar event was called')
  }
 });

var myView = new MyView();
var channel = Radio.channel('myChannelName');
channel.request('foo:bar'); // Logs 'foo:bar event was called'

Пример в браузере

Первый параметр, this, — контекст текущей сущности.

Второй параметр, channel, ссылка на канал по имени.

Третий параметр — хэш либо { 'event:name': 'eventHandler' } либо { 'event:name': 'eventHandler', 'event:otherName': 'otherEventHandler', ...} конфигурации.

Marionette.unbindRequests

Этот метод используется для отмены привязки запросов радио к методам целевого объекта. Все объекты Marionette имеют этот метод.

Вызов этого метода без хэша запросов радио отменит все запросы с канала.

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

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

var MyView = Mn.View.extend({
  channelName: 'myChannelName',

  radioRequests: {
    'foo:bar': 'fooBar'
  },

  onAttach: function() {
    var channel = Radio.channel(this.channelName);
    Mn.bindRequests(this, channel, this.radioRequests);
  },

  onDetach: function() {
    var channel = Radio.channel(this.channelName);
    Mn.unbindRequests(this, channel, this.radioRequests);
  }
 });

Примеры в браузере

Первый параметр, this, — контекст текущей сущности.

Второй параметр, channel, ссылка на канал по имени.

Третий параметр — хэш либо { 'event:name': 'eventHandler' } либо { 'event:name': 'eventHandler', 'event:otherName': 'otherEventHandler', ...} конфигурации.

Marionette.normalizeMethods

Принимает хэш имён событий и функций/имен функций и возвращает тот же хэш с именами функций, заменёнными на сами ссылки на функции. Все классы Marionette, такие как Views, имеют этот метод.

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

var View = Mn.View.extend({

  initialize: function() {
    var hash = {
      'action:one': 'handleActionOne', // This will become a reference to `this.handleActionOne`
      'action:two': this.handleActionTwo
    };

    this.normalizedHash = this.normalizeMethods(hash);
    // or equivalent Mn.normalizeMethods(this, hash);
  },

  do: function(action) {
    this.normalizedHash[action]();
  },

  handleActionOne: function() {
    console.log('action:one was fired');
  },

  handleActionTwo: function() {
    console.log('action:two was fired');
  }

});

var myView = new MyView();
myView.do('action:one');
myView.do('action:two');

Пример в браузере

Marionette.noConflict

Позволяет запускать несколько экземпляров Marionette в одном приложении. После загрузки новой версии вызовите noConflict() для получения ссылки на неё. В то же время старая версия будет возвращена в Backbone.Marionette.

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

var MnV3 = require('backbone.marionette/v3');

// Creates non-conflicting reference to secondary Marionette instance
MnV3 = MnV3.noConflict()