Функции Marionette

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

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

• Marionette.extend
• Marionette.isNodeAttached
• Marionette.mergeOptions
• Marionette.getOption
• Marionette.proxyGetOption
• Marionette.triggerMethod
• Marionette.bindEntityEvents
• Marionette.triggerMethodOn
• Marionette.bindEntityEvent
• Marionette.unbindEntityEvents
• Marionette.proxyBindEntityEvents
• Marionette.proxyUnbindEntityEvents
• Marionette.normalizeMethods
• Marionette.normalizeUIKeys
• Marionette.normalizeUIValues
• Marionette.actAsCollection

Marionette.extend

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

var Foo = function(){};

// use Marionette.extend to make Foo extendable, just like other
// Backbone and Marionette objects
Foo.extend = Marionette.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 div = document.createElement('div');
Marionette.isNodeAttached(div);
// => false

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

Marionette.mergeOptions

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

var MyView = ItemView.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);
  }
});

Marionette.getOption

Получает атрибут объекта непосредственно из объекта или из this.options, с this.options имеющим приоритет.

var M = Backbone.Model.extend({
  foo: "bar",

  initialize: function(attributes, options){
    this.options = options;
    var f = Marionette.getOption(this, "foo");
    console.log(f);
  }
});

new M(); // => "bar"

new M({}, { foo: "quux" }); // => "quux"

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

Значения false

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

Например:

var M = Backbone.Model.extend({
  foo: "bar",

  initialize: function(){
    var f = Marionette.getOption(this, "foo");
    console.log(f);
  }
});

new M(); // => "bar"

var f;
new M({}, { foo: f }); // => "bar"

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

Marionette.proxyGetOption

Этот метод делегирует Marionette.getOption, чтобы его можно было легко добавить в экземпляр.

Предположим, вы написали свой собственный класс Pagination, и вы всегда передаёте в него параметры. С помощью proxyGetOption, вы можете легко добавить в этот класс функцию getOption.

_.extend(Pagination.prototype, {

  getFoo: function(){
    return this.getOption("foo");
  },

  getOption: Marionette.proxyGetOption
});

Marionette.triggerMethod

Вызывает событие и соответствующий метод в целевом объекте.

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

• triggerMethod("render") вызывает функцию "onRender"
• triggerMethod("before:destroy") вызывает функцию "onBeforeDestroy"

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

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

Обратите внимание, что triggerMethod может быть вызван на объектах, в которые не включён Backbone.Events. У этих объектов не будет метода trigger, и не будет попытки вызвать .trigger(). Однако обратные вызовы on{Name} всё равно будут вызваны.

Marionette.triggerMethodOn

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

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

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

Marionette.bindEntityEvents

Этот метод используется для связывания "сущности" Backbone (например, коллекции/модели) с методами в целевом объекте.

Backbone.View.extend({

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

  initialize: function(){
    Marionette.bindEntityEvents(this, this.model, this.modelEvents);
  },

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

});

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

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

Третий параметр — хэш { "имя_события": "обработчик_события" }. Несколько обработчиков могут быть разделены пробелом. Вместо строкового имени обработчика можно передать функцию.

Marionette.unbindEntityEvents

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

// Just like the above example we bind our model events.
// This time, however, we unbind them on close.
Backbone.View.extend({

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

  initialize: function(){
    Marionette.bindEntityEvents(this, this.model, this.modelEvents);
  },

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

  onClose: function() {
    Marionette.unbindEntityEvents(this, this.model, this.modelEvents);
  }

});

Marionette.proxyBindEntityEvents

Этот метод делегирует Marionette.bindEntityEvents для лёгкого добавления в экземпляр.

Предположим, вы написали свой собственный класс Pagination, и хотите легко слушать события некоторых сущностей. С помощью proxyBindEntityEvents, вы можете легко добавить в этот класс функцию bindEntityEvents.

_.extend(Pagination.prototype, {

   bindSomething: function() {
     this.bindEntityEvents(this.something, this.somethingEvents)
   },

   bindEntityEvents: Marionette.proxyBindEntityEvents

});

Marionette.proxyUnbindEntityEvents

Этот метод делегирует Marionette.unbindEntityEvents для лёгкого добавления в экземпляр.

Это противоположность proxyBindEntityEvents, описанной выше. Следовательно, API одинаковы для каждого метода.

Предположим, вы написали свой собственный класс Pagination, и хотите легко отвязать обратные вызовы от событий некоторых сущностей. С помощью proxyUnbindEntityEvents, вы можете легко добавить в этот класс функцию unbindEntityEvents.

_.extend(Pagination.prototype, {

   bindSomething: function() {
     this.bindEntityEvents(this.something, this.somethingEvents)
   },

   unbindSomething: function() {
     this.unbindEntityEvents(this.something, this.somethingEvents)
   },

   bindEntityEvents: Marionette.proxyBindEntityEvents,

   unbindEntityEvents: Marionette.proxyUnbindEntityEvents

});

Marionette.normalizeMethods

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

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

var View = Marionette.ItemView.extend({

  initialize: function() {
    this.someFn = function() {};
    this.someOtherFn = function() {};
    var hash = {
      eventOne: "someFn", // This will become a reference to `this.someFn`
      eventTwo: this.someOtherFn
    };
    this.normalizedHash = this.normalizeMethods(hash);
  }

});

Marionette.normalizeUIKeys

Этот метод позволяет использовать синтаксис @ui. в заданном ключе для хэшей триггеров и событий. Он меняет ссылку @ui. на соответствующий селектор.

var hash = {
  'click @ui.list': 'myCb'
};

var ui = {
  'list': 'ul'
};

// This sets 'click @ui.list' to be 'click ul' in the newHash object
var newHash = Marionette.normalizeUIKeys(hash, ui);

Marionette.normalizeUIValues

Этот метод позволяет использовать синтаксис @ui. в заданном значении хэша (например, хэши регионов). Он меняет ссылку @ui. на соответствующий селектор.

var hash = {
  'foo': [email protected]'
};

var ui = {
  'bar': '.quux'
};

// This sets 'foo' to be '.quux' in the newHash object
var newHash = Marionette.normalizeUIValues(hash, ui);

Marionette.actAsCollection

Вспомогательная функция для добавления поведения коллекции Underscore в объект.

Она работает, принимая объект и поле свойства, в данном случае 'list', и добавляя функции коллекции к объекту, чтобы он мог делегировать вызовы коллекции своему списку.

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

var obj = {
  list: [1, 2, 3]
}

Marionette.actAsCollection(obj, 'list');

var double = function(v){ return v*2};
console.log(obj.map(double)); // [2, 4, 6]

Прототип функции

var Func = function(list) {
  this.list = list;
};

Marionette.actAsCollection(Func.prototype, 'list');
var func = new Func([1,2,3]);


var double = function(v){ return v*2};
console.log(func.map(double)); // [2, 4, 6]

Первый параметр — объект, который будет делегировать методы коллекции Underscore.

Второй параметр — поле объекта, которое будет содержать список.