Framework for building UIs for OpenStack projects dealing with complex input data
Go to file
Timur Sufiev c25b7d8507 Use standard modelMixin instead of fields.wildcard
Call it fields.generic in exports - it has the same meaning for merlin
code (any field that Merlin provides), less code the better.

Change-Id: Id2eb8fbfa477c014f6e6eebdd9fb0e4298bb029c
2015-08-05 10:12:31 +00:00
bin Add karma testing 2015-04-17 15:27:11 +03:00
extensions Use standard modelMixin instead of fields.wildcard 2015-08-05 10:12:31 +00:00
merlin Use standard modelMixin instead of fields.wildcard 2015-08-05 10:12:31 +00:00
tools Rewrite Merlin as a collection of Django apps for Horizon integration 2014-10-16 19:32:50 +04:00
.eslintignore Initial import of data schema from Rackspace HotBuilder 2015-08-05 10:12:11 +00:00
.eslintrc Use eslint-config-openstack 2015-07-15 13:51:32 -07:00
.gitignore Refactor third-party libraries usage and clean up karma config 2015-04-25 19:18:52 +00:00
.gitreview Added .gitreview 2014-08-28 23:51:02 +00:00
Gruntfile.js Add FAQ and glossary 2015-07-06 14:52:47 +03:00
README.md Add FAQ and glossary 2015-07-06 14:52:47 +03:00
bower.json Refactor templates to make them composable 2015-07-30 12:06:01 +03:00
karma-unit.conf.js Add patched version of angular-ui bootstrap lib 2015-07-31 15:44:26 +03:00
nodeenv.sh Add karma testing 2015-04-17 15:27:11 +03:00
package.json Start developing HOT Builder on Merlin 2015-08-05 10:12:03 +00:00
requirements.txt Rewrite Merlin as a collection of Django apps for Horizon integration 2014-10-16 19:32:50 +04:00
test-requirements.txt Rewrite Merlin as a collection of Django apps for Horizon integration 2014-10-16 19:32:50 +04:00
tox.ini Add karma testing 2015-04-17 15:27:11 +03:00

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
  1. node_modules/.bin/bower install
  2. sudo npm install -g grunt-cli
  3. 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.