3rd-Party Frameworks Integration API

You can use DevExtreme widgets with other frameworks, not just the ones supported out of the box (Angular, AngularJS, Knockout). This article describes how to use DevExtreme widgets and configure them to support templates and two-way binding when working with a 3rd-party framework.

NOTE
All examples in this article demonstrate using DevExtreme widgets without jQuery integration, which is disabled if the jQuery library is not linked or linked after DevExtreme scripts.

Create and Configure a Widget

To create a widget, call its constructor passing the target element and a configuration object. The target element may need to have additional style properties set, for example, data visualization widgets' display should be set to "block".

import Accordion from 'devextreme/ui/accordion';
...
let container = document.getElementById("root");
let element = document.createElement("div");
container.appendChild(element);
let instance = new Accordion(element, options);
...

If you do not use modules, access the widget's constructor via the DevExpress.ui namespace.

let instance = new DevExpress.ui.dxAccordion(element, options);

Change Widget Options and Handle Events

A specific widget instance is required to call methods and subscribe to events. Call the widget class's static getInstance(element) method to retrieve the existing widget instance.

// Modular approach
import Accordion from 'devextreme/ui/accordion';
...
let element = document.getElementById("myAccordion");
let instance = Accordion.getInstance(element);

// Non-modular approach:
let element = document.getElementById("myAccordion");
let instance = DevExpress.ui.dxAccordion.getInstance(element);

You can get and set widget options at runtime using the option() method.

// Get an option value
let isVisible = instance.option("visible");

// Set an option value
instance.option("visible", false);

To subscribe to an event, you can use an option whose name starts with "on" (for example, "onItemClick").

Accordion(element, {
    ...,
    onItemClick: function(e){
        alert("An item is clicked!");
    }
})

Alternatively, you can use the "on()" method.

instance.on("itemClick", function(e){
    alert("An item is clicked!");
})

Advanced Configuration

Specify the widget's integrationOptions option to provide two-way binding and template support.

DevExpress.ui.dxAccordion(element, {
    ...
    integrationOptions: {
        watchMethod: ...
        templates: ...
        createTemplate: ...
    }
})

The integrationOptions configuration object contains the following fields:

  • watchMethod

    This field accepts the following function:

    function(expressionGetter, callback, watchOptions)

    Where

    • expressionGetter - An expression being watched. Accepts a function or string.

    • callback - A callback is called when the watcher is first set and each time it detects a value is changed for the expressionGetter during the internal evaluation loop.

    • watchOptions - An object containing two Boolean fields:

      • skipImmediate - Specifies whether to skip the first value comparison.

      • deep - Specifies whether the watcher uses deep or shallow comparison.

    • The method should return a function that is called when watchers related to the widget are deleted.

  • templates

    This field holds a map of the templates that are added when the widget is initialized. Item keys should correspond to template names. Item values should be objects that contain render functions.

    templates: {
        itemTemplate: {
            render: function (renderData){
                // 'renderData' includes the following fields:
                // 'model' - data to be applied on markup
                // 'itemIndex' - index of item in collection (or id in hierarchical collections)
                // 'container' - append rendered markup to this element
                ...
            }
        }
    }

    The render function should return an HTML element containing the rendered template.

  • createTemplate

    A function that processes a custom template. It accepts an HTML markup or a DOM node passed to a widget's ...Template option and returns an object with a render function.

    createTemplate: function(source) {
        var template = Hogan.compile(source);
        return {
            render: function(args) {
                return template.render(args.data);
            }
        };
    }

In some cases, templates are removed at runtime, for example, when items are updated. To delete resources allocated to removed templates, handle to the dxremove event.

integrationOptions: {
    templates: {
        "item": {
            render: function(args) {
                var div = document.createElement("div");
                new Button(div ,{
                    text: args.model
                });
                var intervalId = setInterval(function() {
                    console.log(args.model);
                }, 500);
                DevExpress.events.on(div, "dxremove", function() {
                    clearInterval(intervalId);
                });
                args.container.appendChild(div);
                return div;
            }
        }
    }
}

Remove a Widget

Use a widget's dispose() method to dispose of the resources allocated to it.

let element = document.createElement("div");
let instance = new Accordion(element, options);
...
instance.dispose();
NOTE

After the dispose method call, the HTML element associated with the widget remains in the DOM. If you need to remove the element as well, use a native API call.

element.remove();