merlin/README.md

Instructions on integrating Merlin extensions into Horizon

Although the repo contains directories meant to be used as Django apps (with templates, static files, urls & views), the whole project is not meant to be run as a standalone Django web-application (with its own settings.py etc). Instead, it should be embedded into running Horizon instance. To do so you should perform the following steps:

1. The easiest way to always use the latest version of Merlin is by using symlinks. Identify the directory where openstack_dashboard and horizon reside. Let's assume this is /usr/lib/python2.7/site-packages and merlin repo is located at /home/user/dev/merlin. Then run the following commands

   # for main Merlin sources
   ln -s /home/user/dev/merlin/merlin /usr/lib/python2.7/site-packages/merlin
   # for files of the Merlin's Mistral extension
   ln -s /home/user/dev/merlin/extensions/mistral /usr/lib/python2.7/site-packages/mistral
   

2. Next thing to do is add panel with Mistral Workbook builder (a Merlin extension) into Horizon. To do it, copy the pluggable config for the Mistral panel:

   cp /home/user/dev/merlin/extensions/enabled/_50_add_mistral_panel.py /usr/lib/python2.7/site-packages/openstack_dashboard/enabled/
   

3. This step is TEMPORARY and will be needed until the real API for listing/ loading/ saving of Mistral workbooks is implemented. You need to add the following setting to the top of /home/user/dev/horizon/openstack_dashboard/local/local_settings.py

   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.sqlite3',
           'NAME': 'horizon.sqlite3'
       }
   }
   

   and run /home/user/dev/horizon/manage.py syncdb after that.

4. Restart Horizon web-server. According to the default values in _50_add_mistral_panel.py you would be able to Mistral panel inside the Project dashboard, Orchestration panel group.

How to run Merlin unit-tests locally

1. cd /home/user/dev/merlin
2. npm install

• If npm is not installed yet, run sudo apt-get install npm (let's assume you're using Ubuntu) and sudo apt-get install nodejs-legacy

3. node_modules/.bin/bower install
4. sudo npm install -g grunt-cli
5. grunt test:unit

Glossary:

• Schema - is a main object for describing structure of a model. This object describes how fields and containers are bounded between themselfs, and how the are being modified. Merlin use schema to validate user input, render forms, fields and models. If you want to define, that if user sets field "type" for "action", that first field in the form should be "Base" - scheme is the place where you should to define it.
• Model - is a prototype for field. Model could describe a different types of fields: strings, text (large string), numer, dictionary, frozendictionary (immutable dictionary), and so on.
• Using models helps to render and validate fields. Uou can extend existing models and create your custom field types. Barricade.js object becames an Merlin object when we add modelMixin. Field - is an atom of form. Should be inherited from some model (Merlin model or your custom model).
• Panel - visual group of containers.
• Container - Barricade-specific object type (immutable objects, arrays, mutable objects).

The final structure of UI is defined by:

• the schema
• the actual data this schema is paired with to create Barricade object
• filters and directives being used in an html for rendering the Barricade object provided on the scope

Merlin filters:

• extractPanels, extractItems, extractRows - used to unpack data from Barricade.js format into format for convenient template rendering. Also, you can apply a few filters for one Barricade object.

FAQ

But where are any controllers?

The are in the app. Сore Merlin code currently doesn't define any controllers because all logic is put into the model, i.e. Barricade objects".

How can I use Merlin in my app?

You can take a look at the /mistral/ directory, which contains Workbook builder app based on Merlin. There is some django-code to render view to show dashboard in the Horizon. And in the merlin/extensions/mistral/static/mistral is Merlin based code. templates/fields contains definition of additional (Mistral-specific) types of fields. You can take a look at merlin/extensions/ directory. In the /enabled/ dir there is typical panel file to add new panel into Horizon Dashboard. mistral.init.js contains fetching custom mistral templates for fields. In this file Angular 'mistral' module is initialized first time, so it should be loaded before any other scripts defining entities within 'mistral' module. mistral.workbook.controllers.js - contains main controller which contains functions for domain-specific actions. For example, actions for creating and initializing Action and Workflow objects.

Lets take a look at the typical definition.

'base-input': {
    '@class': fields.dictionary.extend({ // which model we are going to use as prototype
      create: function(json, parameters) {
        var self = fields.dictionary.create.call(this, json, parameters);
        self.setType('frozendict');
        return self;
      }
    }, {
      '@required': false,
      '?': { //'?' is a marker for Barricade MutableObject
        '@class': fields.string.extend({}, {
          '@meta': { '@meta' tells Merlin how to render it
            'row': 0
          }
        })
      },
      '@meta': {
        'index': 2,
        'title': 'Base Input'
      }
    })
},

How does Merlin know how to render field, panel or group?

Merlin uses templates for this. Each type of field has its own template with html and css-markup, so you can define filters, directives, on-click events, and rules for filling variables for each type of field. The same mechanism is implemented for groups and panels.

How does Merlin gets/sets model value with barricade.js?

Each model has getter/setter, so, when you access to model.value field, if you doing it without param, you calling getter, if you pass any param - you calling a setter. For proper work of this feature we have to use ng-model-options="{getterSetter: true}" ability of angular.js. Currently angular-ui bootstrap library has a bug which doesn't allow use getterSetter: true, and since it is a problem for autosuggestion feature, we filed a bug (and a patch) to the angular-ui repo (ling), and until it will not be released, we managed to use patched version of this library. That's why we have ui-bootstrap-tpls-0.13.0.patched.js file in custom-lib directory.