MVVM / Declarative Initialization And HTML5 Data Attributes

Since the introduction of Custom Data Attributes in the HTML5 spec, developers have discovered a whole new world of possibilities.  When you combine the ability to store arbitrary information in an HTML element with the power of JavaScript, you get some very interesting alternative development experiences.

One of the places where it has become very popular in the JavaScript community at large, is providing information to the underlying JavaScript framework (such as MVVM) which allows the executing code to mutate the HTML element; thusly doing things such as binding it to data, transforming it into a custom UI control or getting configuration values off of it that can’t be stored in the standard provided HTML attributes.

Kendo UI uses this syntax heavily.  In order to be able to use the full power of Kendo UI, you really need to know what you can bind with data attributes, when to use it so it benefits you most and how to use it in concert with Kendo UI as a whole.  In order to provide some clarity around this, it really needs to be discussed in two separate contexts.

1. Using the data-bind syntax with MVVM

2. Using data- syntax with declarative widget initialization/configuration

data-bind / MVVM

Lets look at the data-bind specific syntax first as it is essential to the Kendo UI MVVM implementation as well as Knockout. To negate the risk of completely repeating myself, I’m not going to cover MVVM conceptually.  You can check out a post here that covers what it is and how you use it. 

Lets dive in.

Assume that we have a simple select list and we want to bind it to the view model.  We declare the HTML and the view model.

This is very basic, but we are using the data-bind to bind the source of the select to the view model things array.  Also note that you can bind to a function as well as I’m doing with data-bind=”text: thingSelection” on the h2.   

But the question now becomes, what else can I bind and how do I do it?

This is well documented in our framework section of the documentation.  On the Overview section, you will find a high level explanation of how to bind with the Kendo UI MVVM framework.  Under the Bindings sub-topic, you will find a complete list of what you can bind to.  For reference, I have included that list here as well.

• Attr
• Checked
• Disabled
• Enabled
• Event
• Html
• Source
• Style
• Text
• Value

We have provided samples with each of these binding declarations to help you understand how and when you can use them.

For instance, lets look at styling the drop down a bit using the data-bind syntax with style.  I can set the drop down width as well as setting its margins by using data-bind and the above referenced style.

data-bind="style: { width: thingsWidth, fontSize: thingsFontSize}"

The width and font-size are now bound to view model properties and the select element will be styled appropriately based on the values in the view model.  The h2 also has its color bound to the view model.  When those properties change, so will the style on the select element.  Feel free to try it for yourself in the above fiddle. 

Whenever you are referencing a css property that has a dash, you eliminate the dash and use lower camel case notation (i.e. fontSize instead of font-size) as is documented here.

Declarative Initialization

The other way of using data attributes with Kendo UI is something that we call Declarative Initialization.  This is the concept of initializing widgets and configuring those widgets with data attributes instead of having to select each element that we want to turn into a widget and configure it with JavaScript.

Let’s take a look at the above example using Declarative Initialization to turn the select into a Kendo UI DropDown List.  We do this by setting the data-role attribute to dropdownlist.  Normally this would be done by calling kendoDropDownList on the element.  Thanks to declarative binding, we don’t have to do that anymore.

Notice that we lost our previous styling.  This is because the ordinary select is now a Kendo UI DropDown which has it’s own styling.  Everything else keeps right on working exactly they way you would expect.

Now we could have several drop downs on a page and we only need to configure them with declarative data attributes instead of having to select each and every one with jQuery and call the kendoDropDownList method on them.

But I Don’t Want MVVM. Can I Still Use Declarative Initialization?

YES.  It has always been our goal to not force things on you.  Declarative Bindings are powerful, but you don’t need to buy into the MVVM pattern to use them.

Let’s rework the above example and get rid of the view model, but this time we’ll bind it to a DataSource and let declarative initialization do all the work for us.

The kendo.init call will initialize whatever piece of the UI is passed in as a reference. Notice that I am only calling init on the main div.  For maximum performance, specify the container for Kendo UI to initialize so it doesn’t have to walk the entire document to find the relevant widgets.

You can see that I have supplied configuration attributes for the drop down list such as data-source which binds the drop down to the Kendo UI DataSource.  Also, I have specified configuration attributes like data-text-field and data-value-field.  You can specify any configuration value with declarative initialization, and it will work.  Attributes like dataTextField become data-text-field.  Bindings are specified as lower case separated by dashes.

Events can be bound as well. Above, I bind to the change event.  When the event is called, this will be the object that fired the event.  In this case, that’s our drop down list.  I can then get its text value and update the h2 tag.

IMPORTANT THINGS TO KNOW

I made that all caps with the hopes that you will read this last section as it’s kind of important.

1. Bindings are not JavaScript.  Do not try and do this…

data-bind="value: if ($(“#div”).html() === “somevalue”)…

That won’t work.  You should be doing that in your view model.  If you aren’t using a view model and you have a good use case for sticking JavaScript into your markup, consider using a Kendo UI Template instead.

2. Kendo UI is not the only framework that uses data attributes for binding.  In fact, its pretty common.  If you find yourself in a situation where you need to mitigate collisions with Kendo UI and some other JS library, you can provide a namespace for Kendo UI and then reference that namespace instead.

kendo.ns="kendo";

// Then

data-bind="value: someValue" // becomes

data-kendo-bind="value: someValue"

Don’t Do Guesswork!

It’s easy when you start using these bindings to try and guess what you can and can’t do.  Instead, refer to the docs for the MVVM framework bindings here, and the standard widget declarative bindings here.  When doing initialization of widgets using configuration attributes in the declarative bindings, simply look up the configuration values so you know what you can and can’t use to configure the widget.

We strive to provide you with all of the resources that you need to quickly develop solutions with Kendo UI.  We take your feedback seriously and we are always looking for better avenues for communicating important framework ideas to you in a way that is straightforward and easy to find.  Hopefully this post sheds some more light on binding with data attributes and where you can find the necessary documentation to get up and running.

Special thanks to Atanas Korchev from the Kendo UI team for providing much of the content and direction for this article.

Download Kendo UI TODAY and don’t forget to register for the launch webinar March 22nd At 10 AM CST for your chance to win an iPad, a Galaxy Tab, a Blackberry Playbook and an iPod touch. Not just one, but all of them.  All you have to do to be eligible to win is register!