KendoUI Grid popup editing and inline editing mixed together


If this is not the first time that you read my posts, you probably know that I actively participate in StackOverflow and you probably have already gone through some post where I write about some question that I think that deserves a little more information.

Few days back someone asked how (if possible at all) to get both popup and inline editing in the same grid. Basically what he was trying to do is using popup when creating a new record and use inline (or incell) for existing records. We might argue if from a standard UX point of view if this is good but I can see some cases where this might make sense so I’ve decided to investigate a little on it and I’ve tried to answer the question.

Mixing popup and inline editing in a grid

Research

The very first thing that I thought about was trying to invoke directly the functions that creates the popup window form for editing a record and the function that switches into inline (or incell) mode. The idea was if I can invoke the internal methods directly, I would be able to trigger the mode that I want defining custom buttons.

But when examining KendoUI code (yes, it’s is not Open Source but as Telerik Most Valuable Professional I have access to it) I see that I need to send extra arguments to the methods for popup and incell and it was not easy (clean) for me getting these arguments.

Second approach was invoking KendoUI Grid addRow method that enters in edit mode and depending on the initialization value, it is going to be “popup” or “inline”. The question was … if I change the edition mode dynamically and not at initialization time, will it be used?

The answer is yes, you can change the option dynamically and next time edit event is triggered the edition mode will change. This is not the case with some options for this and other Kendo UI Widget that once the widget is created, they will not read back the options.

How to implement it

What I had to do is:

  1. Initialize the Grid for using, by default, inline mode.
  2. Define a Custom button in the toolbar that looks like the standard “Add new row” but executes our own code.
  3. Define the button handler that forces the edition mode to “popup”, invokes editRow and restores previous edition mode (“inline”)

This would be something like

var grid = $("#grid").kendoGrid({
    dataSource: ds,
    toolbar: [ 
        {
            // My own version of "Add new record" button, with name **popup**
            text : "Add new record", 
            name: "popup", 
            iconClass: "k-icon k-add"
        }
    ],
    // By default is **inline**
    editable: "inline",
    ...
}).data("kendoGrid");

Here we can see that I’ve created in the toolbar a button with name “popup” and showing the text “Add new record”, the same being displayed by the default “create” button. Finally, I’ve define the icon that should be displayed in the button having the button look exactly the same than the standard “create” button.

The second important question is that I’ve defined “editable” as “inline” so it is expected that I define an “edit” button for each row and when clicked, it enters in “inline” edition.

Now, the missing part: attach a click event handler attached to my “popup” button. This is:

// Event handler for my **popup** button defined in the grid toolbar
$(".k-grid-popup", grid.element).on("click", function () {
    // Temporarily set editable to "popup"
    grid.options.editable = "popup";
    // Insert row
    grid.addRow();
    // Revert editable to inline
    grid.options.editable = "inline";
});

Binding a function to the click event for buttons defined in the toolbar is defining using “on” jQuery method for the CSS class “.k-grid-” in our case since “name” is equal to toolbar, we use the CSS “.k-grid-popup”.

As you can see is a pretty simple process, pretty clean and you don’t have to do a lot of code edition or source code change.

You can play with it in this JSFiddle.

Advertisements

KendoUI Context Menu: too cool!


Today KendoUI announced its new release KendoUI Professional Q2 2014 and during the video presentation they have shown the new Widget ContextMenu.

Despite of attending the presentation I did want to play with it and learn more about this Widget. What is the best way for quickly getting familiar with Kendo UI Widgets? Yes, you are right, their Demo web site but there is no demo about this widget, is that possible? Sure they will fix it pretty soon.

KendoUI Context Menu

What is a Context Menu? According Wiki definition:

A context menu (also called contextual, shortcut, and popup or pop-up menu) is a menu in a graphical user interface (GUI) that appears upon user interaction, such as a right-click mouse operation.

What is a ContextMenu for Kendo UI?

For Kendo UI is an HTML unordered list (pre) that might happen to have more than one level (another unordered list).

Something like:

<ul id="context-menu">
    <li>Option 1
        <ul>
            <li>Option 1.1</li>
            <li>Option 1.2</li>
            <li>Option 1.3
              <ul>
                <li>Option 1.3.1</li>
                <li>Option 1.3.2</li>
                <li>Option 1.3.3</li>
                <li>Option 1.3.4</li>
              </ul>
          	</li>
        </ul>
    </li>
    <li>Option 2
        <ul>
            <li>Option 2.1</li>
            <li>Option 2.2</li>
            <li>Option 2.3</li>
        </ul>
    </li>
</ul>

And this looks like:

KendoUI Context Menu
KendoUI Context Menu

Defining a ContextMenu

In the previous paragraphs I have shown how to define the content of the Context Menu but we should say which are the target elements on which this Context Menu is activated. To do so, you define in the initialization the target elements using a jQuery Selector.

Example:

$("#context-menu").kendoContextMenu({
    target: "#area1,#area2"
});

Here I define that the context menu is going to be displayed if you right-click on an HTML element which id is “area1” or “area2”. Any other part of your HTML will not display it.

Defining a ContextMenu as DataSource

Despite I’ve shown how to initialize the content of the Context Menu using an HTML unordered list (ul) you can also use a DataSource or an array as follow:

var ds = [
    {
        text: "Europe"
    },
    {
        text : "Americas",
        items: [
            {
                text : "North America",
                items: [
                    { text: "Canada" },
                    { text: "United States" },
                    { text: "Mexico" }
                ]
            },
            { text: "Central America" },
            {
                text : "South America",
                items: [
                    { text: "Argentina" },
                    { text: "Brazil" },
                    { text: "Chile" }
                ]
            }
        ]
    },
    {
        text: "Asia"
    }
];
$("

“).kendoContextMenu({ dataSource: ds, target: “#area1” });

KendoUI Context Menu using a DataSource
KendoUI Context Menu using a DataSource

Where each option is an entry in the array and nested option are nested elements stored in an array called “items”.

Since this context menu is actually not defined in HTML I’ve used “$(‘

‘).kendoContextMenu({…});” for creating an HTML element that will contain the menu.

Additional options for the menu items

I’ve shown how to just display a text but you can actually decorate the text using any HTML by doing:

    { text: "United States", encoded: false },

Here I’ve decorated the text as bold (b) and I have set “encoded” to “false” indicating that “<” and “>” should actually not be displayed as a character but being part of the HTML tag.

The following image shows what happen if I define the content of the context menu as:

...
    items: [
        { text: "Canada", encoded: true },
        { text: "United States", encoded: false },
        { text: "Mexico" }
    ]
...
KendoUI Context Menu using HTML codes
KendoUI Context Menu using HTML codes

You can also define a CSS class:

.ob-red {
    background : red;
}
.ob-green {
    background : green;
}
...
    items: [
        { text: "Argentina", cssClass: "ob-red" },
        { text: "Brazil" },
        { text: "Chile", cssClass: "ob-green" }
    ]
...
KendoUI Context Menu using cssClass
KendoUI Context Menu using cssClass

Or you can also add images using “spriteCssClass” or “imageUrl”:

.ob-flag-argentina {
    background-image: url(/images/flags/argentina.png);
}
...
    items: [
        { text: "Argentina", spriteCssClass: "ob-flag-argentina"  },
        { text: "Brazil", imageUrl: "/images/flags/brazil.png" },
        { text: "Chile" }
    ]

That looks like:

KendoUI Context Menu with images
KendoUI Context Menu with images

Reusing KendoUI Menu

The new Context Menu widget actually is pretty similar to Kendo UI Menu, it accepts most of the Menu options and the DataSource are reusable as well. This is how the Menu looks like if I use previous DataSource for defining a Menu.

KendoUI Menu
KendoUI Menu

KendoUI masked text boxes


One of the new widgets just introduced in Kendo UI is kendoMaskedTextBox. This is something that we have been waiting for long time… no need to keep waiting. We can start today enjoying it. Let’s see how.

Introduction to KendoUI MaskedTextBox

What is a maked input field? Their definition: Define and restrict the data to be entered in an html input field.

Let me show it with an example, you have to define an input field and you want to control that what the user types follows some specific format (v.g. telephone number, credit card number, date…) so you are implicitly defining some validation rules. Both the user types it with the format that you want and it gets displayed with the correct format.

kendoMaskedTextBox: Defining a mask for a phone number

In my country, the telephone number are 9 digits and you typically have them in the format 999-999-999. So I want to define an input fields that only allows me to type phones so they have to be all digits and as soon as you finish a group of three the cursor moves to the next group.

What you would have is something like:

Masked Telephone

or when empty:

Masked input empty

And the definition is as simple as:

<br />
$("#phone_number").kendoMaskedTextBox({<br />
    mask: "000-000-000",<br />
    value: "555123456"<br />
});<br />

or you can define using just HTML doing:

<div>
    <label for="phone_number">Phone number:</label>
    <input id="phone_number" data-role="maskedtextbox"
           data-mask="000-000-000" value="555123456">
</div>

Pretty simple and powerful!

kendoMaskedTextBox: Defining masks, the syntax

Kendo UI masked input predefines a series of mask rules (what to accept on each position of the mask). These are the predefined masks.

  1. 0 – Digit. Accepts any digit between 0 and 9.
  2. 9 – Digit or space. Accepts any digit between 0 and 9, plus space.
  3. # – Digit or space. Like 9 rule, but allows also (+) and (-) signs.
  4. L – Letter. Restricts input to letters a-z and A-Z. This rule is equivalent to [a-zA-Z] in regular expressions.
  5. ? – Letter or space. Restricts input to letters a-z and A-Z. This rule is equivalent to [a-zA-Z] in regular expressions.
  6. & – Character. Accepts any character. The rule is equivalent to \S in regular expressions.
  7. C – Character or space. Accepts any character. The rule is equivalent to . in regular expressions.
  8. A – Alphanumeric. Accepts letters and digits only.
  9. a – Alphanumeric or space. Accepts letters, digits and space only.
  10. . – Decimal placeholder. The decimal separator will be get from the current culture used by Kendo.
  11. , – Thousands placeholder. The display character will be get from the current culture used by Kendo.
  12. $ – Currency symbol. The display character will be get from the current culture used by Kendo.

kendoMaskedTextBox: Defining custom masks

But you do not have to use only those predefined mask rules, you might define your own.

Example: Defining a mask that allows typing only even numbers is as simple as:

$("#all-even").kendoMaskedTextBox({
    mask: "eeee",
    rules: {
        "e": /[02468]/
    }
});

Where I define that the input supports 4 characters which mask rule is an e and then I define what e means by defining a rule that says that e might be a digit in the group 02468.

But the rule might even be a function. So this can also be implemented as:

$("#all-even").kendoMaskedTextBox({
    mask: "eeee",
    rules: {
        "e": function(d) {
            return d % 2 == 0;
        }
    }
});

Simply cool!!!

kendoMaskedTextBox: assigning values

This is important to note. In widgets as KendoDateTimePicker when you initialize the widget with an invalid date, this is displayed as it is until you edit the field.

Example: I initialize the DatePicker to February 29th, 2014 but this day does not exist. What we see is:

Initializing mask text box with invalid value

And when we enter in edition mode we get:

Pick a date

But, kendoMaskedTextBox works in a different way, the characters defined in the initialization are like typed by you and those that do not met the rule restriction are simply ignored.

So if we define a value of 12345678 for our 4 even digits mask, what we will get is:

Initializing mask text box with invalid value

$("#all-even").kendoMaskedTextBox({
    mask: "eeee",
    rules: {
        "e": "/[02468]/"
    },
    value: 123456789
});

That shows that the date that we used during the initialization is just ignored.

kendoMaskedTextBox: Still some features missing

This is actually a great widget. The only limitation that I’ve found is that masks do not support repeating factor something like saying that a number repeated seven times (something like 9(3) meaning that a digit between 0 and 9 repeated 3 times) or that some character mask should be typed between n and m times (something like 9(1..3) meaning that a number between 0 and 9 repeated between 1 and 3 times).

KendoUI Q1’14 Release just announced


Telerik just announced their KendoUI Q1’14 Release and this time they bring a lot of cool new widget and some very interesting new options for old ones.

In this post I will list some of this cool options that I’ve already been able to test while in Beta and now I can enjoy in its full flavor.

New Widgets

There are some cool and very nice widget as:

  1. Notification: Very easy and non blocking notifications for your sites. Forget about alerts or have to handcraft popup windows. They provide you new notifications even with custom categories (not just warning and errors) and you can choose where to display them (top, bottom, left, right, fixed position, contained, floating…), for how long (they can autohide after some period of time), they can be templated,…
  2. MaskedTextBox: This is likely my favorite one because of the long time waited. Yes, you can finally have masked text box for telephones, credit cards, or you can even create your own. This actually deserves a post by itself that I’m already writing.
  3. Sortable: This is actually a widget per se but it is also used in Grid were you can move rows and sort them. Really nice effect!!!
  4. “Real-time” DataSource: Wow!!! this is also cool. Have two grids, listviews… and see what you do in one being updated in the other. Do you remember what I did with Dropbox in the post ? Now you have the same effect with plain KendoUI. This is a new level of Observable Objects
  5. Grid Frozen Columns: another new options for making Kendo UI Grids even better. Now you might have some columns stick where they are when you scroll horizontally. Perfect when you have large amount of data or even better when your screen size is not that large.

Please, go to their demo web site and see them in action. It’s worthy.

KendoUI DataSources + Dropbox DataStore: Change Listener


My last posts were about Dropbox DataStore and Kendo UI DataSource. I have demonstrated how to read, create, delete and update records.

And I have shown how the original example provided with Dropbox was able to listen for changes in my application and automatically synchronize those changes.

I want to do the same! When Dropbox sample code changes the DataStore content, I want that my grid automatically gets updated.

Event listeners in DataStore Dropbox

We have seen in previous videos how when we create, update or delete a record from our Grid, the HTML sample code from Dropbox magically gets updated. This is because Dropbox provide a mechanism for registering a function (a listener) to changes in the DataStore. What Dropbox library does is that when you updates the copy in Dropbox server, it notifies the library and this calls you.

dataStore.recordsChanged.addListener(function(ev) {
    // Event handler code...
});

What we do in this event handler is either getting the changes and update the affected rows or fully update the table.

In my case and for simplicity, I’m going to update the complete Grid by invoking `DataSource.read()` method. Something like:

// Add listener for changes
dataStore.recordsChanged.addListener(function(ev) { taskTableDS.read() });

NOTE: If I just add these lines of code to what I have in my previous post, I will get an error because in the current implementation I was expecting that the DataStore was opened only one: so I was not closing it and I could try opening it twice if DataStore.read happen to be called twice.

So I need to slightly change readTask code to control that the DataStore is alreayd open and not try to do it again.

function readTasks(op) {
    if (client.isAuthenticated()) {
        // Client is authenticated. Display UI.
        if (dataStore === null) {
            var datastoreManager = client.getDatastoreManager();
            datastoreManager.openDefaultDatastore(function (error, datastore) {
                if (error) {
                    alert('Error opening default datastore: ' + error);
                }
                dataStore = datastore;

                // Add listener for changes
                dataStore.recordsChanged.addListener(function (ev) { taskTableDS.read() });

                taskTable = datastore.getTable('tasks');
                op.success(taskTable.query());
            });
        } else {
            op.success(taskTable.query());
        }
    }
}

And the complete code is:

// Insert your Dropbox app key here:
var DROPBOX_APP_KEY = '0sh....';

// Exposed for easy access in the browser console.
var client = new Dropbox.Client({key: DROPBOX_APP_KEY});
var taskTable = null;
var dataStore = null;

// Try to finish OAuth authorization.
client.authenticate({interactive: true}, function (error) {
    if (error) {
        alert('Authentication error: ' + error);
    }
});

function parseItem(elem) {
    return {
        id       : elem.getId(),
        taskname : elem.get("taskname"),
        created  : elem.get("created"),
        completed: elem.get("completed")
    };
}

function readTasks(op) {
    if (client.isAuthenticated()) {
        // Client is authenticated. Display UI.
        if (dataStore === null) {
            var datastoreManager = client.getDatastoreManager();
            datastoreManager.openDefaultDatastore(function (error, datastore) {
                if (error) {
                    alert('Error opening default datastore: ' + error);
                }
                dataStore = datastore;

                // Add listener for changes
                dataStore.recordsChanged.addListener(function (ev) { taskTableDS.read() });

                taskTable = datastore.getTable('tasks');
                op.success(taskTable.query());
            });
        } else {
            op.success(taskTable.query());
        }
    }
}

function parseDropboxRecords(d) {
    var res = [];
    $.each(d, function (idx, elem) {
        res.push(parseItem(elem));
    });
    return (res);
}

var taskTableDS = new kendo.data.DataSource({
    transport: {
        read   : function (op) {
            readTasks(op);
        },
        update : function (op) {
            var data = op.data;
            var id = data.id;
            // Remove id to do not have it duplicated
            delete op.data.id;
            var record = taskTable.get(id).update(data);
            op.success([record]);
        },
        destroy: function (op) {
            taskTable.get(op.data.id).deleteRecord();
            op.success();
        },
        create : function (op) {
            // Remove id to do not have it duplicated
            delete op.data.id;
            var record = taskTable.insert(op.data);
            op.success([record]);
        }
    },
    schema   : {
        model: {
            id    : "id",
            fields: {
                id       : { type: "string" },
                taskname : { type: "string" },
                created  : { type: "date", editable: false },
                completed: { type: "boolean" }
            }
        },
        parse: parseDropboxRecords
    }
});

$("#grid").kendoGrid({
    dataSource: taskTableDS,
    editable  : "popup",
    toolbar   : ["create"],
    columns   : [
        { command: ["edit", "destroy"], width: 180 },
        { field: "taskname", width: 80 },
        { field: "created", format: "{0:G}", width: 200 },
        { field: "completed", width: 70 }
    ]
});

Which looks like:

KendoUI Grid: custom sorting algorithms


There was a couple of times that I have had to sort columns in a KendoUI Grid but using my custom order. I mean, not using out-of-the-box ordering but doing something especial. Example: order ignoring accents, upper-lower case… but I couldn’t find how to do easily do it and end-up implementing server side filtering and sending the data sorted from the server. For what I was looking for, that was acceptable but this is not always desirable.

This week Atanas Korchev (@korchev) from Telerik, show us how to do it in Stack Overflow: easy and neat! Let me show you how.

KendoUI Grid: defining sortable columns

This is pretty easy, just define sortable: true in your Grid and it will work.

$("#grid").kendoGrid({
    dataSource: {
        data    : [
            { id: 1, name: "one" },
            { id: 2, name: "two" },
            { id: 3, name: "three" },
            { id: 4, name: "four" },
            { id: 5, name: "five" }
        ],
        pageSize: 10,
        schema  : {
            model: {
                fields: {
                    id  : { type: 'number' },
                    name: { type: 'string' }
                }
            }
        }
    },
    editable  : false,
    pageable  : false,
    sortable  : true,
    columns   : [
        { field: "id", title: "Number" },
        { field: "name", title: "Name" }
    ]
});

And you get:

Sortable Grid
Sortable Grid

and if you click on the column header it will sort the column numerically or alphabetically.

KendoUI Grid: Defining custom order

But, what about if you want to order the column by Name but you want that it should be considered as numbers…

If we look at KendoUI documentation about sortable we can define it at Grid level:

Sortable Grid option
Sortable Grid option

and at column level:

KendoUI Grid column sortable option
KendoUI Grid column sortable option

But despite the first says Can be set to a JavaScript object which represents the sorting configuration it does not provide any detail.

At least now, we have some details. Here is how to define a custom compare function.

KendoUI Grid: Custom compare function

Despite the documentation says that columns.sortable needs to be a Boolean it actually can be an object and one of the members of this object is a compare function that return -1 if first argument is less than seconde, 0 if both are the same or +1 if the second is greater that then first.

{
    field   : "name",
    width   : 200,
    title   : "Name",
    sortable: {
        compare: function (a, b) {
            return numbers[a.name] - numbers[b.name];
        }
    }
}

Now, for the sake of this example, what I do is defining an associative array for translating number names into numbers (this is only an example!).

var numbers = {
    "one"  : 1,
    "two"  : 2,
    "three": 3,
    "four" : 4,
    "five" : 5
};

Now, my grid definition is:

var grid = $("#grid").kendoGrid({
    dataSource: {
        data    : [
            { id: 1, name: "one" },
            { id: 2, name: "two" },
            { id: 3, name: "three" },
            { id: 4, name: "four" },
            { id: 5, name: "five" }
        ],
        pageSize: 10,
        schema  : {
            model: {
                fields: {
                    id  : { type: 'number' },
                    name: { type: 'string' }
                }
            }
        }
    },
    editable  : false,
    pageable  : false,
    sortable  : true,
    columns   : [
        { field: "id", title: "Number" },
        {
            field   : "name",
            title   : "Name",
            sortable: {
                compare: function (a, b) {
                    return numbers[a.name] - numbers[b.name];
                }
            }
        }
    ]
}).data("kendoGrid");

And when sorting what I get is:

KendoUI Grid custom sorted
KendoUI Grid custom sorted

KendoUI Grid: custom sorting strings

Have you ever tried sorting a column with string with mixed upper-lower case, accents…? Seems that KendoUI engineers have considered that we want alphabetical order (which is very useful) and not ASCII order.

Let’s consider that we have the following data in our DataSource

[
    { id: 1, name: "Johan" },
    { id: 2, name: "john" },
    { id: 3, name: "Jöhän" },
    { id: 4, name: "john" },
    { id: 5, name: "John" },
    { id: 6, name: "john" }
]

Where we see John in uppercase (record with id 5) and in lowercase (record with id 2, 4 and 6) or Johan with different punctuations.

If we define a Grid with this data and sort it by column name

var grid = $("#grid").kendoGrid({
    dataSource: {
        data    : [
            { id: 1, name: "Johan" },
            { id: 2, name: "john" },
            { id: 3, name: "Jöhään" },
            { id: 4, name: "john" },
            { id: 5, name: "John" },
            { id: 6, name: "john" }
        ],
        pageSize: 10,
        schema  : {
            model: {
                fields: {
                    id  : { type: 'number' },
                    name: { type: 'string' }
                }
            }
        }
    },
    editable  : false,
    pageable  : false,
    sortable  : true,
    columns   : [
        { field: "id", title: "Number" },
        { field: "name", title: "Name" }
    ]
}).data("kendoGrid");

What I get is:

Sorting name with default compare function
Sorting name with default compare function

That show that “Jöhään” is lower than “Johan” and “john” is always lower than “John” (odd?!)

Let’s define a sorting function using standard order. What I will do show side by side two grids with the same data.

My Grid definition is:

var grid1 = $("#grid1").kendoGrid({
    dataSource: {
        data    : [
            { id: 1, name: "Johan" },
            { id: 2, name: "john" },
            { id: 3, name: "Jöhään" },
            { id: 4, name: "john" },
            { id: 5, name: "John" },
            { id: 6, name: "john" }
        ],
        pageSize: 10,
        schema  : {
            model: {
                fields: {
                    id  : { type: 'number' },
                    name: { type: 'string' }
                }
            }
        }
    },
    editable  : false,
    pageable  : false,
    sortable  : true,
    columns   : [
        { field: "id", title: "Number" },
        { field: "name", title: "Name" }
    ]
}).data("kendoGrid");
var grid2 = $("#grid2").kendoGrid({
    dataSource: {
        data    : [
            { id: 1, name: "Johan" },
            { id: 2, name: "john" },
            { id: 3, name: "Jöhään" },
            { id: 4, name: "john" },
            { id: 5, name: "John" },
            { id: 6, name: "john" }
        ],
        pageSize: 10,
        schema  : {
            model: {
                fields: {
                    id  : { type: 'number' },
                    name: { type: 'string' }
                }
            }
        }
    },
    editable  : false,
    pageable  : false,
    sortable  : true,
    columns   : [
        { field: "id", title: "Number" },
        {
            field   : "name",
            title   : "Name",
            sortable: {
                compare: function (a, b) {
                    return a.name === b.name ? 0 : (a.name > b.name) ? 1 : -1;
                }
            }
        }
    ]
}).data("kendoGrid");

You can se that for the first Grid I do not define any “special” sortable option while for second, I defined a compare function that returns 0, 1 or -1.

compare: function (a, b) {
    return a.name2 === b.name2 ? 0 : (a.name2 > b.name2) ? 1 : -1;
}

Now, if I order incrementally by name both Grids, I get:

String column with custom compare function.
String column with custom compare function.

Where now uppercase come before lowercase and non accented character also before than same with accent or punctuation.

KendoUI using templates in Menus: Yes, we can!


Is it possible using template in KendoUI Menus? No, as it is (out of the box) But of course you can with very little programming.

KendoUI Menu: the basics

Creating a Menu with Kendo UI is pretty simple, just define a list of items and then invoke kendoMenu.

This is the HTML code:

<ul id="menu">
    <li>
        Europe
    </li>
    <li>
        Americas
    </li>
    <li>
        Asia
    </li>
</ul>

and this is the JavaScript:

$(document).ready(function () {
    $("#menu").kendoMenu();
});

And it looks like:

Basic Kendo UI menu
Basic Kendo UI menu

KendoUI Menu: nested options

Nesting options in Kendo UI menu is as simple as before, just define nested lists in your top level list.

Now, HTML looks like:

<ul id="menu">
    <li>
        Europe
    </li>
    <li>
        Americas
        <ul>
            <li>
                North America
                <ul>
                    <li>Canada</li>
                    <li>United States</li>
                    <li>Mexico</li>
                </ul>
            </li>
            <li>Central America</li>
            <li>South America</li>
        </ul>
    </li>
    <li>
        Asia
    </li>
</ul>

And now, it looks like:

KendoUI Menu: nested options
KendoUI Menu: nested options

KendoUI: using datasource initialization

But we don’t have to initialize the Menus from HTML list, we can also use KendoUI datasource. The initialization of previous menu is:

HTML code:

<div id="menu"></div>

And the JavaScript:

$(document).ready(function () {
    $("#menu").kendoMenu({
        dataSource: [
            {
                text : "Europe"
            },
            {
                text : "Americas",
                items: [
                    {
                        text : "North America",
                        items: [
                            { text: "Canada" },
                            { text: "United States" },
                            { text: "Mexico" }
                        ]
                    }
                ]
            },
            {
                text   : "Asia"
            }
        ]
    });
});

KendoUI Menu: Customizing it

There are a few option pretty useful for customizing a Menu item. Most important are:

  • imageUrl: URL to an image displayed before the item text.
  • spriteCssClass: CSS class for displaying an image before the item text.
  • cssClass: CSS class for menu item.

Modifying our previous example as follow:

JavaScript code:

$(document).ready(function () {
    $("#menu").kendoMenu({
        dataSource: [
            {
                text: "Europe"
            },
            {
                text : "Americas",
                items: [
                    {
                        text : "North America",
                        items: [
                            { text: "Canada" },
                            { text: "United States" },
                            { text: "Mexico" }
                        ]
                    },
                    { text: "Central America" },
                    {
                        text : "South America",
                        items: [
                            { text: "Argentina", cssClass: "ob-red", spriteCssClass: "ob-flag-argentina"  },
                            { text: "Brazil", imageUrl: "images/flags/brazil.png" },
                            { text: "Chile", cssClass: "ob-green" }
                        ]
                    }
                ]
            },
            {
                text: "Asia"
            }
        ]
    });
});

and the CSS classes are defined as:

.ob-flag-argentina {
    background-image: url('images/flags/argentina.png');
}

.ob-red {
    background-color: red !important;
    color: white !important;
}

.ob-green {
    background-color: green !important;
    color: white !important;
}

And it would look like:

KendoUI Menu: customizing apperance
KendoUI Menu: customizing apperance

KendoUI Menu: using HTML in text

Next step is using your own HTML as text for an item. This is also supported by defining the item as:

{
    text: "Asia",
    items : [
        { text: "<span style='border: 1px solid red;'>China</span>", encoded: false },
        { text: "<span style='border: 1px solid blue;'>India</span>", encoded: false }
    ]
}

and looks like:

KendoUI Menu: defining  item as HTML
KendoUI Menu: defining item as HTML

KendoUI Menu: using templates

I know that documentation on Kendo UI Menu is not good but there is no template option in KendoUI Menu, I had to do it by myself. Here I show you what you need to do.

The idea about the implementation

What I’m going to be doing is crawling the DataSource structure looking for each item if they have a template entry. If so, I use it as a template definition, using the result of expanding the template as text of item and setting encoded to false.

And this is the recursive function that crawls the data applying the template:

function transformText(nodes) {
    for (var i = 0; i < nodes.length; i++) {
        var node = nodes[i];
        if (node.template) {
            var template = kendo.template($("#" + node.template).html());
            node.text = template(node);
            node.encoded = false;
            // Remove this from node to do not get it twice
            node.spriteCssClass = undefined;
            node.imageUrl = undefined;
            node.cssClass = undefined;
        }
        if (node.items) {
            transformText(node.items);
        }
    }
    return nodes;
}

and the Menu initialization would be:

$("#menu").kendoMenu({
    dataSource: transformText([
        {
            text : "Europe",
            items: [
                { text: "Bulgaria", imageUrl: "images/flags/bulgaria.png" },
                { text: "Germany", imageUrl: "images/flags/germany.png" },
                { text: "Spain", imageUrl: "images/flags/spain.png" }
            ]
        },
        {
            text : "Americas",
            items: [
                {
                    text : "North America",
                    items: [
                        { text: "Canada", spriteCssClass: "ob-flag-canada"  },
                        { text: "United States", spriteCssClass: "ob-flag-usa" },
                        { text: "Mexico", spriteCssClass: "ob-flag-mexico"  }
                    ]
                },
                {
                    text : "Central America",
                    items: [
                        { text: "Costa Rica", template: "template", id: 2, spriteCssClass: "ob-flag-costa-rica" },
                        { text: "Nicaragua", template: "template", cssClass: "ob-yellow" },
                        { text: "Panama", template: "template", imageUrl: "images/flags/panama.png" }
                    ]
                },
                {
                    text : "South America",
                    items: [
                        { text: "Argentina", cssClass: "ob-red", spriteCssClass: "ob-flag-argentina"  },
                        { text: "Brazil", imageUrl: "images/flags/brazil.png" },
                        { text: "Chile", cssClass: "ob-green" }
                    ]
                }
            ]
        },
        {
            text   : "Asia",
            enabled: true,
            group  : [
                { text: "Australia" }
            ]
        }
    ])
});

Example using a Kendo UI template in a Menu

This example does the same than default menu behavior but introduces an id for each menu item (if defined, othersie a GUID) and displays the image after the text (instead of before).

<script type="text/kendo-ui" id="template">
    <span class="${data.cssClass}" id="#= data.id || kendo.guid() #">${text}</span>
    # if (data.imageUrl) { #
    <img src="${data.imageUrl}" alt="" class="k-image ob-flag-right">
    # } #
    # if (data.spriteCssClass) { #
    <span class="k-sprite ob-flag-right ${data.spriteCssClass}"></span>
    # } #
</script>

and the result looks like:

KendoUI menu: Using a template how we want each item to look like
KendoUI menu: Using a template how we want each item to look like