JS Widget Components

A JS Widget is a component whose content is drawn by your own JavaScript code. Use it to turn a third-party JavaScript library, such as D3 or three.js, into a DGLux5 component. The widget's properties appear in the Property Inspector like the parameters of a symbol, so you can set them and bind them to data like any other component property.

The dglux5_js_lib project on GitHub contains a ready-to-use widget template, the three.js and D3 libraries, and examples:

github.com/dglux/dglux5_js_lib

1. Download or clone dglux5_js_lib.
2. On the DGLux5 server, create a project named js in the files/proj directory, and copy all files from the repository into it.
3. Open the js project in DGLux5. Open any .dg5 file in the examples folder to see an example.

The repository contains:

1. In your project, right-click the lib folder in the Project panel and import the js project as a library.
2. A blank JS Widget template now appears in the widget palette. Drag it to the stage.
3. In the Property Inspector, set the Symbol field to the JavaScript file that defines your widget, for example lib/js/examples/parameters/parameters.js. The field also accepts an http:// or https:// URL.
4. The widget's parameters appear in the Property Inspector. Set or bind them as usual.

The template has a light gray background so that you can see it on the stage. You can remove it in the Fill and Stroke section.

A widget is a JavaScript file that calls dgdefine and returns an object with a dgNewWidget function. dgNewWidget receives the div that the widget draws into and returns a new widget object. The widget class extends dgluxjs.Widget.

This minimal widget has one input property, text, and one output property, length:

dgdefine([], function () {
 
    var MyWidget = (function (_super) {
        __extends(MyWidget, _super);
 
        function MyWidget(div, model) {
            _super.call(this, div, model);
            this.contentDiv = document.createElement('div');
            div.appendChild(this.contentDiv);
        }
 
        // The properties shown in the Property Inspector
        MyWidget.prototype.getDefinition = function () {
            return {
                "name": "",
                "variables": [
                    { "t": "string", "n": "text" },
                    { "t": "number", "n": "length" }
                ],
                "layout": {
                    "type": "vbox",
                    "children": ["text", "length"]
                }
            };
        };
 
        // Called when a property value changes
        MyWidget.myPropMap = {
            "text": function (widget, value) {
                widget.contentDiv.textContent = value;
                widget.updateModelValue("length", value ? value.length : 0);
            }
        };
        MyWidget.prototype.getPropMap = function () {
            return MyWidget.myPropMap;
        };
 
        // Called when the widget is removed
        MyWidget.prototype.destroy = function () {
            this.contentDiv.remove();
        };
 
        return MyWidget;
    }(dgluxjs.Widget));
 
    function dgNewWidget(div, model) {
        return new MyWidget(div, model);
    }
    return { "dgNewWidget": dgNewWidget };
});

getDefinition() returns an object with these fields:

Methods that you can override:

Methods and fields that you can use:

DGLux5 loads widget files with its own AMD-style module loader, dgdefine. List the files your widget needs as the first argument of dgdefine. The modules they return are passed to your function in the same order:

dgdefine(["lib/js/three/three.r82.min.js"], function (THREE) {
    // THREE is available here
});

• Paths that start with lib/ refer to the project's lib folder. Other relative paths are relative to the widget file, and .js is added if it is missing.
• A library file that is not written for dgdefine must tell DGLux5 what it exports. Add a dgdefine call to the end of the library file. For example, the copy of three.js in the repository ends with:

dgdefine([], function () {
    return THREE;
});

See examples/threejs in the repository for a complete example.