As you may know, we have created our own architecture for creating Controls in JavaScript. So, now I'd like to show you how to write custom Controls that extend our wijmo.Control class. This sample is going to use TypeScript, as we do for all of our Controls. I will provide the runtime JavaScript, which you can also use as a basis for creating Wijmo 5 Controls. This source code for this sample is available in our download. I also published a working version of the custom Control in action.
Dependencies
First we need to include the following:
- jQuery 2.x
- wijmo.js (Includes base Control class)
- wijmo.d.ts (Optional TypeScript definition)
Create the Control
Our Control is going to be simple, it will simply display a caption and button in a panel. This Control is not really useful, but meant to demonstrate how to create a Control. First, we create a new TypeScript file called MyControl.ts. Now, we add our Controls class that extends the base class wijmo.Control.
/**
* A Custom Control that extends the wijmo.Control class.
*/
class MyControl extends wijmo.Control {
}
Next, we add our private references and our static member controlTemplate. The controlTemplate is something that all Wijmo 5 Controls use as their initial markup. This can be overridden and offers advanced developers the ability to modify our Control's markup. The key is the wj-part attributes that we use to determine important parts of a Control.
// references to inner elements
_lbl: HTMLElement;
_btn: HTMLButtonElement;
/**
* Gets the template used to instantiate @see:MyControl controls.
*/
static controlTemplate = '<div style="cursor:default">' +
'<p>This is <b>MyControl</b></p>' +
'<p wj-part="lbl"></p>' +
'<button wj-part="btn">The button!</button>' +
'</div>';
Next, we add any public properties we want to expose in our Control. In this instance we only have a single property: caption.
/**
* Gets or sets the text shown above the button.
*/
get caption(): string {
return this._lbl.textContent;
}
set caption(value: string) {
// use asString to ensure type is correct
this._lbl.textContent = wijmo.asString(value);
}
We also add any events we want to expose. In this case, we will add a single buttonClicked event. These events can be subscribed to and triggered from outside the Control.
/**
* Occurs when the button is clicked.
*/
buttonClicked = new wijmo.Event();
/**
* Raises the @see:buttonClicked event.
*/
onButtonClicked(e?: wijmo.EventArgs) {
this.buttonClicked.raise(this, e);
}
Lastly, we create our constructor for the Control. The constructor is where we apply the controlTemplate and specify which parts it contains. We also bind events to elements that require raising Control events. We set any initial property values needed and initialize our Control.
/**
* Initializes a new instance of a @see:MyControl.
*
* @param element The DOM element that will host the control, or a jQuery-style selector (e.g. '#theCtrl').
* @param options JavaScript object containing initialization data for the control.
*/
constructor(element: any, options?) {
super(element);
// instantiate and apply template
var tpl = this.getTemplate();
this.applyTemplate('wj-control', tpl, {
_btn: 'btn',
_lbl: 'lbl'
});
// raise buttonClicked event when the button is clicked
var self = this;
this._btn.addEventListener('click', function () {
self.onButtonClicked();
});
// initialize control
this.caption = 'Hello Wijmo!';
if (options) {
this.initialize(options);
}
}
Now just compile this TypeScript file and you have your first Wijmo 5 Control.
Result
The result is a custom Wijmo 5 Control that can be reused in your applications. Take a look at the working Control in action on jsfiddle. This tutorial is included as a sample in our download, if you want to use it as a starting point for making your own custom Control.
Chris Bannon