widget development guidelines

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

---

Widget Development Guidelines

This represents a collection of rules that should be followed when implementing a Kendo UI control wrapper in Aurelia.

See the Widget Implementation Walkthrough for an implementation example

Leveraging Aurelia Conventions

Important: we MUST be explicit when defining metadata for a custom-attribute or custom-element. Aurelia's conventions can be customised and the plugin library will not know if any customisations have been made.

This means you must include decorators to describe your custom element:

import {customElement} from 'aurelia-framework';

@customElement('my-element')
export class MyElement {
}

Custom-Elements vs Custom-Attributes

Kendo UI controls which have no native DOM representation (e.g. a grid, treeview etc) should be implemented as custom elements.

<au-kendo-grid option1.bind="property"
      option2.bind="property2"> ... etc

Controls which are based on existing elements such as the DatePicker which wraps an input control should be implemented as custom attributes.

<input au-kendo-datepicker value.bind="property">

This allows the developer to naturally bind to the value property on the input.

Note: it's necessary to raise a dummy input.change event in the case of the above in order to update the binding system when the value changes. See http://www.danyow.net/jquery-ui-datepicker-with-aurelia/ for an example. This will go into a utility module.

Kendo-Templates

Several of the Kendo UI controls use kendo-templates.

The Kendo templating system uses language that overlaps Aurelia interpolations. This requires a hack at present to prevent your Aurelia templates from being hijacked so we need to look into this more thoroughly and see if there is any merit in putting a shared component together so that the control implementations stay clean.

This is, however, optional but I think there is a very strong case to integrate the two, the Kendo templating system cannot see the Aurelia viewmodels and is limited to the scope of the data passed to it. The only way to get hold of the Aurelia viewmodel would be to include it in the datasource which seems like a massive hack to me.

Integration makes this possible:

<au-kendo-grid>
    <au-kendo-grid-column>
        <p>This is a template for an item: ${ $item.someProperty } - this looks at the parent ${ $parent.someMethod() }</p>
    </au-kendo-grid-column>
</au-kendo-grid>

Naming Conventions

Elements

Our wrappers DOM names should have a prefix to prevent them from colliding with:

• Developers custom-elements/attributes
• Telerik's potential implementation which may happen at some point
• Aurelia's own aurelia-interface UI project which uses <ai-widget-name>

I propose:

<au-kendo-xxxxx>

Viewmodels

Naming of viewmodels doesn't really matter but for consistency they should match the conventions that Aurelia would expect (even though we are being explicit). For example:

<my-kendo-control>

// Should be named

export class MyKendoControl { ...

Application structure

The sample application is hosted within the plugin repository (for ease of development). This means that all development on the plugins themselves should happen in the /src directory

The sample application resides in the /sample directory, here a page should be created to test/demo the widget and showcase all the features.

A folder should be created for each component:

root
   /src
      /grid
      /autocomplete
   /sample
      app.html
      app.js
      /grid
         index.html
         index.js
         grid_page1.html
         grid_page1.js
         grid_page2.html
         grid_page2.js
      /autocomplete
         index.html
         index.js
         autocomplete_page1.html
         autocomplete_page1.js

...etc

The sample application should use the top navbar to list the index files for each area and use a child router to jump to the demo page for each showcased feature