control implementation walkthrough

Note: this document is a copy of the matching KendoUI Aurelia document. It needs to be updated to describe related Syncfusion EJ document

---

This guide walks you through the implementation of a simple Kendo UI control. Check the document How to build and use aurelia kendoui plugin for more information on how the plugin itself is constructed and organized

Note: Use http://aurelia-ui-toolkits.github.io/demo-kendo In order to get the direct view of the sample/src based "Plugin embedded" application.

Top level categorization

KendoUI controls are integrated with Aurelia using either Custom Attributes or Custom Element approach. In order to do that we need to know when to use either approach. A simple rule of thumb is this

If the KendoUI control is a "sub-class" of an HTML <input control (button being a good example) we will use the Custom Attributes approach. In all other cases, we will use the Custom Element (likely combined with Custom Attributes approach).

---

Example: KendoUI Button control

In the Kendo development model, a button is rendered using a code sample like this:

<button id="primaryTextButton" class="k-primary">Primary Button</button>
...
<script>
    $(document).ready(function () {
        $("#primaryTextButton").kendoButton();
    });
</script>

In the matching Aurelia development model, this same effect is achieved as

<button au-kendo-button class="k-primary">Primary Button</button>

where the au-kendo-button attribute is an Aurelia Custom Attribute class shown in the Appendix of this document.

The screen-shot below is taken from the Kendo-Demo application that shows all KendoUI controls integrated with Aurelia.Primary Button

---

Integration process "cheat-sheet"

Let's start with the definition of the Aurelia KendoUI Plugin internal structure.

1. Plugin section (folder src)

• For each KendoUI Control create a folder, named the same as the control (like src/button ) and create the JavaScript file named after the control that contains the code for the Custom Attribute - as shown in the Appendix for the Button Custom Attribute.

• Create the filesrc/index.js that defines the interface between the plugin and the consuming application (contained in the sample/src folder in this example.

Note: see index.js for the current version of this interface

2. Embedded application section (folder sample/src)

• For each KendoUI Control create a folder, named the same as the control (like sample/src/button )

• Using the Telerik's Kendo Demo site define the set of demo cases - choices for button control are shown below:

• Each demo case is implemented in Aurelia's standard way: view and view-model - these two specific references point to the Button API demo case.

2.1

Add the "button routing section" to the file sample/src/app.js

...
        },  {
            route: 'button',
            moduleId: 'button/index',
            nav: true,
            title: 'Button'
        },  {
...

This results with the appearance of the button menu item on the menubar:

2.2

Add the button folder to the sample/src folder

2.3

Create three pairs of HTML/JS files (views and view models):

• api.html and api.js
• basic-use.html and basic-use.js
• images.html and images.js

which create the sidebar for rendering the selection of various button use cases

Step 2.4

Add the sample/src/button/index.js file (which defines the "sidebar navigation"

import {useView} from 'aurelia-framework';

@useView("shared/showcase.html")
export class Index {

    configureRouter(config, router) {
        config.title = 'Button';
        config.map([{
            route: ['', 'basic-use'],
            moduleId: './basic-use',
            nav: true,
            title: 'Basic Use'
        }, {
            route: 'images',
            moduleId: './images',
            nav: true,
            title: 'Images'
        }, {
            route: 'api',
            moduleId: './api',
            nav: true,
            title: 'API'
        }, ]);

        this.router = router;
    }
}

See also How to build and use aurelia kendoui plugin to find more details.

---

Appendix

Definition of the au-kendo-button Custom Attribute class:

import {customAttribute, bindable, inject} from 'aurelia-framework';
import {pruneOptions} from '../common/options';
import $ from 'jquery';
import 'kendo-ui/js/kendo.button.min';

@customAttribute('au-kendo-button')
@inject(Element)
export class AuKendoButton {

    _component;

    @bindable enable = true;
    @bindable icon;
    @bindable imageUrl;
    @bindable spriteCssClass;

    @bindable options;

    constructor(element) {
        this.element = element;
        this.options = {};
    }

    bind() {
        this._component = $(this.element).kendoButton(this.getOptions()).data('kendoButton');
    }

    detached() {
    	if(this._component)
	        this._component.destroy();
    }

    getOptions() {

        var options = pruneOptions({
            icon: this.icon,
            enable: this.enable,
            imageUrl: this.imageUrl,
            spriteCssClass: this.spriteCssClass
        });

        return Object.assign({}, this.options, options);
    }

    enableChanged(newValue) {
    	if(this._component)
    		this._component.enable(newValue);
    }
}