1 of 10

Merlin

A cross-project UI framework

Timur Sufiev, Mirantis

Drago Rosson, Rackspace

2 of 10

Where do OpenStack UIs fail

Hard to input data in form of YAML templates

A lot of interdependencies, special DSL
Users should consult the documentation
Easy to make an error
Hard to debug

Affected projects: Mistral, Heat, Murano

3 of 10

How should good UI behave

Prevents errors

Imposes YAML structure restrictions
Offers values auto-completion
Provides validation hints

Facilitates understanding

Represents YAML document as a graph

Still allows to edit raw YAML

4 of 10

Provide a tool, not a solution

A tool for building UIs, not a single UI
Provide a reference UI implementation as well

Mistral Workbook Builder is the first one

Seamless Horizon integration

But even three aforementioned projects - Mistral, Heat and Murano -

have completely different teams of developers and different goals. So

it's impossible to anticipate every UI feature they are going to

need. Instead of this Merlin project aims to provide a good set of

tools each team could use on their own to build UIs they need. Among

the core functionality Merlin also provides a reference UI

implementations, in a manner similar to the Horizon project. The

reference implementation we’ve started with was the Mistral Workbook

Builder because it’s the simplest one among the three projects.

Another goal we had in mind from the very beginning was the seamless

integration into Horizon, to facilitate the relocataion of Merlin code

into Horizon repo at some point in future (well, I hope it will be

soon).

5 of 10

Assisted Editing UI pattern

The forms view: hinted template editing - input restriction, validations and autocompletions

Switch between YAML and Graph view

The YAML view: raw

template editing

6 of 10

Live Demo!

Merlin-powered UI in action

Now, before I dive into the technical details, I’d like to show you

the Mistral Worbook Builder UI in action.

We start with an empty list of Mistral workbooks - the container

entities for all the actions, workflows and tasks that Mistral is

going to execute in an isolated environment.

[Press ‘Create Workbook’]

Here we have the top-level Workbook properties and nothing

else. Notice how the changing field values is reflected in the YAML

view. [Change workbook name and description] Every field has its type

and a corresponding default value when nothing is specified.

The required fields - for example, the workbook name, - should not be

empty and Merlin framework ensures that it's really the case. [Make name

field empty and observe danger message]

Now let’s add a Workflow to our Workbook. To be useful the Workflow

needs to have at least one Task within it [Press ‘plus’ for Tasks]

Every task can either execute some custom Mistral Action or launch

another Workflow. Okay, first I create a new custom Action [press

Create Action] and choose the standard OpenStack action which is being

subclassed [choose nova]. See how the set of Base input fields change

every time I change the base Action [change Base to neutron, then to

glance].

Now if I return to the task and start typing the Action it should

execute, we got just one suggestion here - action1. Now see what

happens if I change the Task type to Workflow based [show it]: the

Workflow field replaces Action field and the options it suggests for

auto-completion are limited to workflow1. These suggestions are

completely dynamic - if I add a new Workflow, it will be reflected in

the list [show it], if I change one of the Workflow id-s, it will be

reflected as well[show it].

7 of 10

Under the hood, the model

Merlin classes

Angular.js integration

model setter/getter
autocompletion
choosing the right template (see later)

list

dictionary

string/number/text

frozendict/panel

Barricade.js classes

Schema enforcement
JSON serialization
Basic validation
Defaults handling

Primitive

ImmutableObj

MutableObj

Array

subclassing

Okay, how does it work? There are 2 main components which contribute

to the highly interactive UI in Merlin. It's the Barricade.js library

(thanks to Drago Rosson) which is used for building deeply-nested

hierarchical data models. The library represents each entry in the

YAML template with a strongly typed JavaScript object. The second

component is the Angular.js framework. It both helps us to instantly &

magically update the DOM with all the changes made to Barricade

objects, and allows for an easy Horizon integration via Angular.js

module system.

A few more words about the data model. The Barricade.js library brings

a strong typing to the fluid and amorphous world of JavaScript by

introducing an object schema. Strictly speaking, first a hierarchy of

Barricade classes is created, with each class has its own schema - and

then the objects we'll be working with are created from those

classes. The container classes - there are 3 flavors of them -

ImmutableObject, MutableObject and Array - can contain any other

class, thus the composition is implemented. Besides ensuring that

the data conforms to the schema and could be both serialized and

de-serialized to JSON/YAML, Barricade also allows us to add custom

validations and handle the default values.

The next important step here is to add some mixins to the vanilla

Barricade objects to make them work together with ng-model directive,

as well as add auto-completion support and html template rendering

machinery. So every distinct input widget that Merlin provides is

backed up with a model class.

8 of 10

Under the hood, the view

Angular factory

Merlin classes

definitions

Angular controller

root-level object

added to $scope

server-side

YAML

=value @type

Final HTML template

.create()

Angular

filters

Mistral WB DOM

<panel>

<group>

<typed-field>

ng-repeat

Render the right template based on model type passed within the scope (postpone template dispatch to directive’s linking phase).

recursively

Now that we have a bunch of Merlin models, how do we assemble an html

from them? Well, for Mistral Workbook Builder we have a top-level

container class, namely Workbook, and once we plug it from Angular.js

factory into the Controller, we create an object from it on the scope.

It either has no data (which means we're creating a new Workbook) or

is filled up with a YAML template received from the Mistral service -

in case we're editing an existing Workbook.

Then we filter this top-level object through a pipeline of Merlin

filters, first we extract some panels, then the rows and

finally the specific items (or widgets). Then using some Merlin

directives such as <panel>, <group> and <typed-field> we finally

render the Barricade objects as an input widgets. By the way,

<typed-field> directive which renders the majority of things in Merlin

could be applied recursively. I mean that a template which is

substituted for a specific Barricade object passed into <typed-field>

directive may contain more occurences of <typed-field>s and they will

be rendered the same way as original directive. This is possible

because the html template is being dispatched on the Barricade

object's type that is passed within the scope, so it's not happening

until the linking phase of a directive.

9 of 10

Horizon integration

Merlin

hz

Mistral

base.html Template

Directives

Filters

Factories

Controllers

Workbook Builder Template

Merlin Framework

Workbook Builder

Horizon Framework

10 of 10

Contacts

Bugtracker http://launchpad.net/merlin
Source-code

Merlin http://github.com/stackforge/merlin
Barricade.js https://github.com/rackerlabs/barricade

Wiki http://wiki.openstack.org/wiki/merlin
IRC Freenode, #openstack-merlin