KendoUI User control - Nesterovsky bros

Tuesday, 26 March 2013

Developing with KendoUI we try to formalize tasks. With this in mind we would like to have user controls.

We define user control as following:

It is a javascript class that extends Widget.
It offers a way to reuse UI.
It allows to define a model and a template with UI and data binding.

Unfortunately, KendoUI does not have such API, though one can easily define it; so we have defined our version.

Here we review our solution. We have taken a grid KendoUI example and converted it into a user control.

User control on the page

See index.html

<!DOCTYPE html> <html> <head> <title>Test</title>  <script src="scripts/templates.js"></script> <script src="scripts/jquery/jquery.js"></script> <script src="scripts/kendo/kendo.web.min.js"></script>  <script src="scripts/controls.js"></script>  <script src="scripts/controls/confirm.js"></script>  <script src="scripts/controls/products.js"></script> <link href="styles/kendo.common.min.css" rel="stylesheet" /> <link href="styles/kendo.default.min.css" rel="stylesheet" /> <script> $(function () { // (5) Bind the page. kendo.bind( document.body, // (6) Model as a datasource. { source: [new nesterovskyBros.data.ProductsModel] }); }); </script> </head> <body>  <div data-role="products" data-bind="source: source"></div> </body> </html>

That's what we see here:

Templates that define layouts. See "How To: Load KendoUI Templates from External Files", and templates.tt.
Definition of the UserControl widget.
Confirm dialog user control (we shall mention it later).
Products user control.
Data binding that instantiates page controls.
Model is passed to a user control through the dataSource.
Use of Products user control. Notice that "data-role" defines control type, "source" refers to the model.

User Control declaration

Declaration consists of a view and a model.

View is html with data binding. See products.tmpl.html

We build our project using Visual Studio, so templates packaging is done with templates.tt. This transformation converts products template into a tag:

<script id="products-template" type="text/x-kendo-template">

thus template can be referred by a utility function: nesterovskyBros.template("products-template").

Model inherits kedo.data.Model. Here how it looks:

// (1) Define a ProducsModel class. nesterovskyBros.data.ProductsModel = kendo.data.Model.define( { // (2) Model properties. fields: { productName: { type: "string", defaultValue: "Product Name" }, productPrice: { type: "number", defaultValue: 10 }, productUnitsInStock: { type: "number", defaultValue: 10 }, products: { type: "default", defaultValue: [] } }, // (3) Model methods. addProduct: function () { ... }, deleteProduct: function (e) { ... }, ... }); // (4) Register user control. nesterovskyBros.ui.Products = nesterovskyBros.defineControl( { name: "Products", model: nesterovskyBros.data.ProductsModel });

That's what we have here:

We define a model that inherits KendoUI Model.
We define model fields.
We define model methods.
Register user control with nesterovskyBros.defineControl(proto) call, where:
- proto.name - defines user control name;
- proto.model - defines model type;
- proto.template - defines optional template. If not specified, a template is retrieved from $("#" + proto.name.toLowerCase() + "-template").html().

UserControl API

Now, what's remained is API for the UserControl. See controls.js.

UserControl defines following events:
- change - triggered when data source is changed;
- dataBound - triggered when widget is data bound;
- dataBinding - triggered befor widget data binding;
- save - used to notify user to save model state.
UserControl defines following options:
- autoBind (default false) - autoBind data source;
- template (default $.noop) - user control template.
UserControl defines dataSource field and setDataSource() method.
UserControl defines rebind() method to manually rebuild widget's view from the template and model.
UserControl sets/deletes model.owner, which is a function returning a user control widget when model is bound/unbound to the widget.
When UserControl binds/unbinds model a model.refresh method is called, if any.
You usually define you control with a call nesterovskyBros.defineControl(proto). See above.
There is also a convenience method to build a dialog based on a user control: nesterovskyBros.defineDialog(options), where
- options.name - a user control name (used in the data-role);
- options.model - a model type;
- options.windowOptions - a window options.
This method returns a function that recieves a user control model, and returns a dialog (kendo.ui.Window) based on the user control.
Dialog has model() function that returns an instance of model.
Model has dialog() function that returns an instance of the dialog.
Dialog and model have result() function that returns an instance of deferred object used to track dialog completion.
The example of user control dialog is confirm.js and confirm.tmpl.html. The use is in the products.js deleteProduct():

deleteProduct: function(e) { var that = this; return nesterovskyBros.dialog.confirm( { title: "Please confirm", message: "Do you want to delete the record?", confirm: "Yes", cancel: "No" }). open(). center(). result(). then( function(confirmed) { if (!confirmed) { return; } ... }); }

Last

User controls along with technique to manage and cache templates allow us to build robust web applications. As the added value it's became a trivial task to build SPA.