Mosaico Plugins

Introduction.

Mosaico currently supports 2 types of plugins:

• widget plugins which allow to add custom property editor to Mosaico.
• viewModel plugins which allow to implement or expand Mosaico' overall behaviour

In addition to this it supports "init"/"dispose" lifecycle. This allows plugins to specify custom specific actions to be performed when Mosaico starts up respectively when it is disposed.

A plugin is an object (or a function) that you can pass to Mosaico.init or to Mosaico.start by passing it in an array. For example (taken from editor.html):

  plugins = [function(vm) {window.viewModel = vm;}];  // this is a plugin
  var ok = Mosaico.init({
    imgProcessorBackend: basePath+'/img/',
    emailProcessorBackend: basePath+'/dl/',
    titleToken: "MOSAICO Responsive Email Designer",
    fileuploadConfig: {
      url: basePath+'/upload/',
      // messages??
    }
  }, 
  plugins         // here we pass the plugins to Mosaico.init
);

viewModel plugins

A viewModel plugin exists in 2 forms:

• function(viewModel) { ... plugin action here ...; return { dispose: function() } : plugin as function
• { viewModel: function(viewModel) {... plugin action here ...}, init: function(), dispose: function() } : plugin as object

Both forms are equivalent. The "function" style plugin is internally converted to the object style plugin.

The simplest plugin is the plugin that expose Mosaico viewModel to the window:

function(viewModel) { window.viewModel = viewModel }

You may want to start adding this one when you develop and this way you can have a look at the "viewModel" core object using your browser console.

The "viewModel" plugins are called after the template have been parsed and the default content has been loaded in the model and the editor has been built, just before starting "knockout" (starting knockout bindings makes the application "live"). Therefore a plugin can override Methods in the viewModel (to learn more about ViewModel see the tutorials on http://knockoutjs.com/). You can watch the plugins to be called by the following plugin:

plugins = [function(vm) {
         alert("test-plugin");
         return {
              init: function(vm){alert("init");}, 
              dispose:  function(vm){alert("dispose");}
             }  
          }
];

In all forms init/dispose are optional depending if the plugin has contributions to Mosaico init or dispose.

TODO: when is init and dispose really called? init does not get an argument?

Let's say you want to override the way Mosaico deals with translations, you can override the "viewModel.t" method by the following plugin.

function(viewModel) { viewModel.t = function() { return 'FOO' } }

This plugin will replace the translation method by another translation method provided by the plugin. This methods itself yields the string "FOO" as translation for every UI string.

app.js:initFromLocalStorage (https://github.com/voidlabs/mosaico/blob/master/src/js/app.js#L105) is a function that could have been written outside from mosaico that simply instantiate a plugin (the localstorage plugin) and calls Mosaico.start passing this plugin.

widget plugins

A widget plugin is something new that you can use to provide custom property editor to mosaico.

var mosaicoWidgetPlugin = {
    widget: function($, ko, kojqui) {
      return {
        widget: 'mypropertytype',
        parameters: { param: true },
        html: function(propAccessor, onfocusbinding, parameters) {
          return '<input size="7" type="text" data-bind="value: ' + propAccessor + ', ' + onfocusbinding + '" />';
        }
      };
    },
    viewModel: function(vm) {
      // of course you can also define helper functions in the viewModel (you can access them in the widget code as $root.function()
    }
  };