MxL Expression Directive

This directive is based on the CodeMirror (v5) code editor control and the ui-codemirror directive.

It allows you to easily add a MxL code editor into your web application. This MxL code editor already supports useful features like MxL-specific syntax highlighting, auto-completion support, and a "try it out" feature.

Note: In the following examples, the MxL code editor is bound to SocioCortex through the sc-angular module.

Requirements

• AngularJS 1.3.x

Usage

Clone the repository into your web application directory and load the following script files into your application:

#!html
<!-- AnguarJS -->
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.13/angular.min.js" type="text/javascript"></script>

<!-- SocioCortex scripts (if you want to bind the MxL to SocioCortex as shown in the examples below) -->
<script src="sc/sc-angular.js" type="text/javascript"></script>

<!-- CodeMirror scripts -->
<script src="mxl/CodeMirror/codemirror.js">   </script>
<script src="mxl/CodeMirror/addon/display/fullscreen.js"></script>
<script src="mxl/CodeMirror/addon/display/panel.js"></script>
<script src="mxl/CodeMirror/addon/edit/matchbrackets.js"></script>
<script src="mxl/CodeMirror/addon/edit/closebrackets.js"></script>
<script src="mxl/CodeMirror/addon/hint/show-hint.js"></script>
<script src="mxl/CodeMirror/addon/lint/lint.js"></script>
<script src="mxl/CodeMirror/addon/search/searchcursor.js"></script>
<script src="mxl/CodeMirror/addon/search/match-highlighter.js"></script>
<script src="mxl/CodeMirror/addon/runmode/runmode.js"></script>

<link rel="stylesheet" href="mxl/CodeMirror/codemirror.css" />
<link rel="stylesheet" href="mxl/CodeMirror/addon/hint/show-hint.css" />
<link rel="stylesheet" href="mxl/CodeMirror/addon/display/fullscreen.css" />
<link rel="stylesheet" href="mxl/CodeMirror/addon/lint/lint.css" />

<!-- MxL scripts -->
<script src="mxl/mxl-angular.js" type="text/javascript"></script>
<script src="mxl/mxl-parse.js"></script>
<script src="mxl/mxl-hint.js"></script>
<script src="mxl/mxl-lint.js"></script>
<link rel="stylesheet" href="mxl/mxl.css" />

Add the mxl module as a dependency to your application module:

#!javascript
var myApp = angular.module('ceapp', ['mxl', 'sociocortex']);

Add the mxl-expression directive as element to your html:

#!html
<mxl-expression ></mxl-expression>

Working with ng-model

The mxl-expression directive supports AngularJS' two-way binding by using the ng-model attribute:

#!html
<mxl-expression ng-model="expr"></mxl-expression>

The mxl-expression directive only supports standard javascript strings as model value, e.g.:

#!javascript
myApp.controller('myController', function ($scope, scService) {
   $scope.expr = "[1, 2, 3].sum()";
}

Note: In this example, the scService is injected into the controller since it used in the examples later on.

Auto Completion Hints

By default, the MxL code editor already proposes the MxL keywords (e.g., find, this, etc.) as hints for the auto completion feature. Additional hints can be provided through the mxl-autocompletionhints attribute:

#!html
<mxl-expression ng-model="expr" mxl-autocompletionhints="autoCompletionHints"></mxl-expression>

Thereby, you can set the additional hints in the controller of your app, e.g., by loading them from SocioCortex:

#!javascript
scService.mxlAutoComplete($scope.workspaceId).then(function (response) {
        $scope.autoCompletionHints = response.data;
    });

The auto-completion can be triggered by either typing a dot (".") or pressing ctrl-space.

Note: Providing the id of a specific workspace ensures the inclusion of workspace-specific identifiers into the list of additional hints, e.g., types and their attributes.

MxL Validation

In order to enable MxL validation, you have to provide a function which will be called by the mxl-expression directive as soon as the model value is changed:

#!html
<mxl-expression ng-model="expr" mxl-validate="validate(modelValue, viewValue)" ></mxl-expression>

If the expression is valid, the function has to return a promise which will be resolved. Otherwise the promise will reject and will pass the proper error message as a parameter to the callback function. When using the $http service or the respective SocioCortex service, you can simply return the promise which is generated by the asynchronous request:

#!javascript
$scope.validate = function (modelValue, viewValue) {
        return scService.mxlValidate(viewValue, $scope.workspaceId);
    };

Note: Providing the id of a specific workspace ensures the validation of the expression in the context of the respective workspace, i.e., workspace-specific identifiers (e.g., types) can be resolved.

Debounced Model Update

By default, the mxl-expression directive updates its model value only after 2 seconds without a change. This should ensure that the validation service is not requested after each minor change of the model value. You can adapt this duration by setting the mxl-debounce attribute of the mxl-expression directive (milliseconds):

#!html
<mxl-expression ng-model="expr" mxl-debounce="5000"></mxl-expression>

"Try it out" Feature

For some cases it might be helpful for the user to run a test of the expression. For this purpose, the mxl-expression directive supports the "Try it out" feature, which can be triggered by pressing ctrl-enter.

To enable this feature, you have to provide the mxl-runtest attribute to the mxl-expression directive:

#!html
<mxl-expression ng-model="expr" mxl-runtest="runTest(value)"></mxl-expression>

As soon as the user triggers the test, the model value will be changed immediately, and the actual value will be passed to the specified runtest function. The result has to be a promise which either resolves (in case of success) and passes the evaluated value as parameter to the callback function, or rejects (in case of failure) and passes the actual error message to the callback function. An exemplary implementation by integrating SocioCortex might look like follows:

#!javascript
$scope.runTest = function (value) {
        return scService.mxlQuery(value, $scope.workspaceId);
    };

MxL Modes

The mxl-expression directive supports three modes which can be specified by the mxl-mode attribute:

• expression (default): The value of the code editor is interpreted as an arbitrary MxL expression
• type: The value of the code editor is interpreted as the specification of an (eventually parameterized) MxL type, e.g., Sequence
• parameters: The value of the code editor is interpreted as a comma-seperated list of parameter declarations, e.g., name:String, n:Number

Note: "Try it out" feature only works in default mode. Furthermore, in modes type and parameters the auto completion hints are restricted to types and workspaces.