Browse Source

Add FAQ and glossary

This patch adds FAQ and glossary
to the readme.md file.
Also this patch adds documentation
for Merlin directives.
Also this patch grunt task for generation
html from markdown.
To run this task run 'grunt md' from the
Merlin directory.

Change-Id: Ifd98fe4d9fa61bf5b7bbd71361763caa93e7ed3e
master
Paul Karikh 3 years ago
parent
commit
bf942fef1c
4 changed files with 100 additions and 1 deletions
  1. 12
    0
      Gruntfile.js
  2. 66
    1
      README.md
  3. 21
    0
      merlin/static/merlin/js/merlin.directives.js
  4. 1
    0
      package.json

+ 12
- 0
Gruntfile.js View File

@@ -52,12 +52,24 @@ module.exports = function(grunt){
52 52
                 // run tests once instead of continuously
53 53
                 singleRun: true
54 54
             }
55
+        },
56
+        markdown: {
57
+            all: {
58
+                files: [{
59
+                    expand: true,
60
+                    src: './README.md',
61
+                    dest: './',
62
+                    ext: '.html'
63
+                }]
64
+            }
55 65
         }
56 66
     });
57 67
     grunt.loadNpmTasks('grunt-karma');
58 68
     grunt.loadNpmTasks('grunt-contrib-concat');
59 69
     grunt.loadNpmTasks('grunt-contrib-uglify');
70
+    grunt.loadNpmTasks('grunt-markdown');
60 71
     grunt.registerTask('test:unit', [
61 72
         'karma:unit'
62 73
     ]);
74
+    grunt.registerTask('md', ['markdown:all'])
63 75
 };

+ 66
- 1
README.md View File

@@ -50,4 +50,69 @@ the **Project** dashboard, **Orchestration** panel group.
50 50
 4. ``sudo npm install -g grunt-cli``
51 51
 5. ``grunt test:unit``
52 52
 
53
-For more info please refer to https://wiki.openstack.org/wiki/Merlin
53
+# Glossary:
54
+
55
+  * 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.
56
+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.
57
+  * 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.
58
+  * 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.
59
+Field - is an atom of form. Should be inherited from some model (Merlin model or your custom model).
60
+  * Panel - visual group of containers.
61
+  * Container - Barricade-specific object type (immutable objects, arrays, mutable objects).
62
+
63
+
64
+ ### The final structure of UI is defined by:
65
+  * the schema
66
+  * the actual data this schema is paired with to create Barricade object
67
+  * filters and directives being used in an html for rendering the Barricade object provided on the scope
68
+
69
+
70
+ ### Merlin filters:
71
+  * extractPanels, extractItems, extractRows - used to unpack data from Barricade.js format
72
+into format for convenient template rendering. Also, you can apply a few filters for one Barricade object.
73
+
74
+# FAQ
75
+ ### But where are any controllers?
76
+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".
77
+
78
+ ### How can I use Merlin in my app?
79
+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.
80
+And in the `merlin/extensions/mistral/static/mistral` is Merlin based code. `templates/fields` contains definition of additional (Mistral-specific) types of fields.
81
+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.
82
+`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.
83
+`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.
84
+
85
+Lets take a look at the typical definition.
86
+```
87
+'base-input': {
88
+    '@class': fields.dictionary.extend({ // which model we are going to use as prototype
89
+      create: function(json, parameters) {
90
+        var self = fields.dictionary.create.call(this, json, parameters);
91
+        self.setType('frozendict');
92
+        return self;
93
+      }
94
+    }, {
95
+      '@required': false,
96
+      '?': { //'?' is a marker for Barricade MutableObject
97
+        '@class': fields.string.extend({}, {
98
+          '@meta': { '@meta' tells Merlin how to render it
99
+            'row': 0
100
+          }
101
+        })
102
+      },
103
+      '@meta': {
104
+        'index': 2,
105
+        'title': 'Base Input'
106
+      }
107
+    })
108
+},
109
+```
110
+
111
+ ### How does Merlin know how to render field, panel or group?
112
+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.
113
+The same mechanism is implemented for groups and panels.
114
+
115
+ ### How does Merlin gets/sets model value with barricade.js?
116
+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.
117
+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.
118
+That's why we have ui-bootstrap-tpls-0.13.0.patched.js file in custom-lib directory.

+ 21
- 0
merlin/static/merlin/js/merlin.directives.js View File

@@ -5,6 +5,12 @@
5 5
   'use strict';
6 6
 
7 7
   angular.module('merlin')
8
+    /*
9
+    * Allows to edit field name in-place.
10
+    * For example, you have a field named 'Input 1' and you want to replace this name with "Base input" value.
11
+    * If you add editable directive to such field, you will get a marker icon near this field,
12
+    * and with clicking on this icon you can type new name and save or discard changes.
13
+    * */
8 14
     .directive('editable', function() {
9 15
       return {
10 16
         restrict: 'E',
@@ -58,6 +64,9 @@
58 64
         }
59 65
       };
60 66
     })
67
+    /*
68
+    * this directive auto-sets the focus to an input field once it is shown.
69
+    * */
61 70
     .directive('showFocus', function($timeout) {
62 71
       return function(scope, element, attrs) {
63 72
         scope.$watch(attrs.showFocus, function(newValue) {
@@ -67,6 +76,9 @@
67 76
         });
68 77
       }
69 78
     })
79
+    /*
80
+    * tells Merlin to render this element as a panel.
81
+    * */
70 82
     .directive('panel', function($parse) {
71 83
       return {
72 84
         restrict: 'E',
@@ -81,6 +93,9 @@
81 93
         }
82 94
       }
83 95
     })
96
+    /*
97
+    * tells Merlin to render this element as a group with ability to collapse.
98
+    * */
84 99
     .directive('collapsibleGroup', function() {
85 100
       return {
86 101
         restrict: 'E',
@@ -102,6 +117,9 @@
102 117
         }
103 118
       }
104 119
     })
120
+    /*
121
+    * sets up the DOM nodes related to validation of model being edited in this widget (and specifies the name of this model on scope).
122
+    * */
105 123
     .directive('validatableWith', function($parse) {
106 124
       return {
107 125
         restrict: 'A',
@@ -132,6 +150,9 @@
132 150
         }
133 151
       }
134 152
     })
153
+    /*
154
+    * retrieves a template by its name which is the same as model's type and renders it, recursive <typed-field></..>-s are possible.
155
+    * */
135 156
     .directive('typedField', ['$compile', 'merlin.templates',
136 157
       function($compile, templates) {
137 158
         function updateAutoCompletionDirective(template) {

+ 1
- 0
package.json View File

@@ -16,6 +16,7 @@
16 16
     "grunt-eslint": "7.0.1",
17 17
     "grunt-html2js": "0.2.9",
18 18
     "grunt-karma": "0.10.1",
19
+    "grunt-markdown": "^0.7.0",
19 20
     "grunt-open": "0.2.3",
20 21
     "grunt-protractor-runner": "1.1.4",
21 22
     "grunt-shell": "1.1.1",

Loading…
Cancel
Save