Hello Kendo UI Part 1

Tuesday, July 17, 2012 by Kendo UI Team Blog | Comments 19

Many weeks back I started a series entitled “ HTML5 For ASP.NET Developers ”. The response was fantastic, and we begin to work our way through the charted waters of modern web development starting from the very beginning.

In Hello jQuery , we went over the absolute fundamentals of working with jQuery in ASP.NET WebForms and looked at how to use some of the developer tools.

In Hello Services , we investigated how to build restful services with WebAPI. This was my personal favorite as I learned a ton doing it, and even did it wrong the first time! Don’t worry, I only posted the right one for you.

In Hello HTML5 we talked about what HTML5 is and is not, and looked at some very basic concepts, such as pollyfilling.

At this point, you should be comfortable enough with the platform and terminology for us to dive in and leverage all we have learned up until now to create an HTML5 application.

All of this build-up, and we are finally ready to talk about the reason you came to this site in the first place. Kendo UI. We will be breaking this up into how ever many modules it takes for us to get a good mastery of Kendo UI in ASP.NET.

In this tutorial, you will work with the most complex widget, the Kendo UI Grid as well as one of the core components, the Kendo UI DataSource . It is absolutely essential to understand how these two work in your app, and how they work together. We will create a grid, and wire it up to an ASP.NET WebAPI service while doing some heavy server lifting along the way.

As always, feel free to watch the screencast, or skip down to the written content.

Screencast

Written Content

This tutorial builds off of the Hello Services module, so it’s highly recommended that you download that project from GitHub here before we get started. If you are interested in seeing the completed solution, you can download that here .

In the Hello Services project, delete the Site.Master , About.aspx and Default.aspx pages. Add a new WebForm to the project and call it Default.aspx .

When the document comes up, delete all of the unnecessary DOCTYPE declaration and HTML namespacing. If you refer to Hello HTML5 , you will remember that none of this is necessary and really just clutters up the code.

Removing the <form>

I’m going to have you remove the form tag, but just a word about why before you actually do it.

The <form> tag in the page is what WebForms uses to post any data in the page back to the server and then back again. By default, WebForms pages post back to themselves. The server then takes this form data (any .NET controls in the page) and manipulates their values based on methods you have defined in the code behind. There is a whole page lifecycle that goes into effect here. Since we are essentially building an SPA , we don’t need this form.

Now that you have removed the form tag, the server tag at the top of the page declaring the page language and code behind is also not necessary. We are going all straight HTML here, so also remove the runat attribute from the head.

Remove Unnecessary Markup

<!DOCTYPE html>
<html>
    <head>
        <title></title>
    </head>
    <body>
    </body>
</html>

Add Kendo UI

Add Kendo UI to your project by installing it from NuGet. This will also install jQuery. Right-click the project and select add library package reference . Select online from the left-hand side and search for kendoui. Select the package and choose install.

While you are free to install and try out Kendo UI, please make sure that you have a licensed copy before using Kendo UI in a production application. Click here for more information on Kendo UI licensing.

Notice that you now have a Content folder that contains a kendo subfolder. You also have a Scripts folder which also has a kendo subfolder.

Add Kendo UI To The Default Page

In order to build with Kendo UI, you need to include it’s styles, jQuery and the Kendo UI JavaScript files. Out of the Content folder and kendo/version subfolder, drag the kendo.common.min.css file to the head of the page, just below <title> . This style sheet always needs to be included. It’s used in all the themes. Next, pick your favorite theme and drag that stylesheet to the head of the page. For this example, I used the default style which is kendo.default.min.css .

Expand the Scripts folder. Select jQuery-1.7.2.min.js and drag it into the body of the page. We put the script files in the body of the page because it’s best practice to load scripts last as they will delay loading of the whole page. Loading them last ensures that your application doesn’t suffer from seemingly poor performance while waiting on a JavaScript file.

Next expand the kendo subfolder (and the appropriate version subfolder under that – 2012.2.710 at the time of this writing) and drag kendo.web.min.js out and drop it just below jQuery. It’s important to load jQuery BEFORE loading Kendo UI as Kendo UI takes a dependency on jQuery and expects it to be loaded.

Type Not Required

It turns out that Script includes do not need a type. If you do not specify a type, it is assumed to be JavaScript and parsed as such. This is safe in every browser. Go ahead and remove the type attribute off the script tags.

When you are done pruning, your code should be very simple and look like this…

Kendo UI Added To The Page

<!DOCTYPE html>
    
<html>
    <head>
        <title>Hello Kendo UI</title>
        <link href="Content/kendo/2012.2.710/kendo.common.min.css" rel="stylesheet" type="text/css" />
        <link href="Content/kendo/2012.2.710/kendo.default.min.css" rel="stylesheet" type="text/css" />
    </head>
    <body>
        
        <script src="Scripts/jquery-1.7.2.min.js"></script>
        <script src="Scripts/kendo/2012.2.710/kendo.web.min.js"></script>
        
    </body>
</html>

We now have everything it takes to get started. Since we already have an employees endpoint from the Hello Services modules, we will use the grid to display those employees. Don’t worry. This is going to get a lot more complex as we go. We are just starting out simple.

Make a grid by adding an empty div to the page with an id of employeesGrid . We will select this later with jQuery to turn it into a Kendo UI Grid .

Grid Markup

<divid="employeesGrid"></div>

Now we need to turn this grid into a Kendo UI Grid using JavaScript. To do that, select the div by it’s ID with a jQuery selector and then call the kendoGrid function. Inside that function, you will need to create the Kendo UI DataSource for the grid and set its read endpoint to the Get method on the EmployeesController . If you don’t recall, the Get method simply specifies that the controller should respond to a GET HTTP request at the api/employees endpoint.

Create A Kendo UI Grid

$(function () {
    $("#employeesGrid").kendoGrid({ 
        dataSource: new kendo.data.DataSource({
            transport: {
                read: "api/employees"
            }
        })
    });
});

Now with that simple piece of markup and small bit of JavaScript, you have created a Kendo UI Grid .

Kendo UI automatically creates columns for each of the data items and assigns the field name as the column header. We want to change this to make it more user friendly. Specifically, we don’t need to display the Id, and we want to format the First Name and Last Name columns so they display headers in spaced title case. Right now they are title cased, but there is no space.

Specify Grid Columns

$(function () {
    $("#employeesGrid").kendoGrid({ 
        columns: [
            { field: “FirstName”, title: “First Name” },
            { field: “LastName”, title: “Last Name” }
        ],
        dataSource: new kendo.data.DataSource({
            transport: {
                read: "api/employees"
            }
        }),
        sortable: true
    });
});

Now the grid displays the column headers correctly and does not display the unnecessary Id column.

You can also enable drag-and-drop grouping by setting the groupable: true flag, as well as multi-column sorting, aggregating, and paging.

This is all great when there are only a few items in your grid. But what happens when there are hundreds of items in the grid. At some point, you want to push actions back to the server. Let’s take a look at how to do that.

Performing Grid Actions Server-Side

Assume that this grid is backed by data with thousands of rows, not just 10. In this case, you would want to do some paging on the grid. You could show possibly 10 rows per page. Maybe 20. While you could easily enable this in the grid client-side, you really need to do this paging on the server. Let’s wire up the grid to the server so that we can perform paging actions on the database which will really boost the performance of massive record sets.

Setup Paging In The Grid

You need to setup paging in the grid first. To do that, simply set pageable: true on the grid, and then set the pageSize on the DataSource. I’m setting the pageSize to 3 since I only have 10 records to work with.

Configure Grid For Paging

$(function () {
    $("#employeesGrid").kendoGrid({ 
        columns: [
            { field: “FirstName”, title: “First Name” },
            { field: “LastName”, title: “Last Name” }
        ],
        dataSource: new kendo.data.DataSource({
            transport: {
                read: "api/employees"
            },
            pageSize: 3
        }),
        pageable: true
    });
});

Now the grid is setup for paging.

You need to push this paging to the server. To tell Kendo UI to do this, simply toggle the serverPaging: true on the DataSource in the grid.

Tell Grid To Send Paging To The Server

$(function () {
    $("#employeesGrid").kendoGrid({ 
        columns: [
            { field: “FirstName”, title: “First Name” }, 
            { field: “LastName”, title: “Last Name” }
        ],
        dataSource: new kendo.data.DataSource({
            transport: {
                read: "api/employees"
            },
            pageSize: 3,
            serverPaging: true
        }),
        pageable: true
    });
});

The grid now displays only 1 page. The reason for this is that it is expecting the server to send it some information that we have not yet specified. Open up the Dev Tools by pressing ctrl+shift+i in Chrome or F12 in IE. You will have noticed that I switched to using Chrome as my primary browser. The reason is simply the robust nature of it’s developer tools when compared to IE. You will want to test your application on whichever browser you are targeting for deployment.

An inspection of the request in the DevTools reveals that Kendo UI is now sending take, skip and pageSize parameters back to the WebAPI service. You need to handle these parameters in the method on the server.

Handling Request Parameters

If you recall from the Hello Services post, you mapped a URL back to a method with an optional id parameter that may or may not be after employees in the URL path. But these parameters for paging are in the query string. How do we get to these parameters?

These parameters can be retrieved off of the Request object. You can create a reference to this variable at the top of your EmployeesController class for brevity. The you just need to look for the parameters by name.

The take parameter tells you how many records you need to fetch (i.e. the page size).

The skip parameter tells you how many records to skip before you start fetching records.

Luckily, LINQ has these functions built right in and they are dead simple to use. Simply retrieve the values off of the Request parameter and then call the Skip and Take methods on your query to the Employees table.

Create A Kendo UI Grid

HttpRequestrequest =HttpContext.Current.Request;publicList

19 Comments

1 Ben Hayat 18 Jul 2012
As always, excellent blog.

Two questions:
a) I noticed you used NuGet to get KendoUI into the project. Let's say, someone has purchased the full KendoUI and installed on their machine that is a "Licensed" copy. When you do a NuGet download, which version do you get into project or for those who have installed it, what would be the best direction to get it to project.
(When I use Telerik Webform controls), as soon as I drop the first control on the form, I get the appropriate Telerik DLL into my References. For the KendoUI, what's the preferred way to get the "Licenced" version into References?

b) Ok, putting this blog together with the previous one (setting up WebAPI Services), you're basically using the ASP.Net Webform to host the WebAPI service and on the client you use KendoUI (none MVC) to consume the service.
Now that KendoUI has a wrapper for ASP.Net MVC, in order to do the same task and the amount of code that had to be written, how much the MVC version would reduce the code and the steps?
I'm just trying to get a measure and scale to see the pros & cons of going either with MVC version or WebAPI route.

I'd appreciate if you can provide us some info to outline these two directions. Where/when should we approach it via WebAPI and when MVC?
Thank you in advance!
..Ben
2 Burke 19 Jul 2012
Hi @Ben

1. When you install off of Nuget, you get the most recent version of Kendo UI Web. Should you install off of Nuget? That's up to you. I would advise using a downloaded version and managing your own Kendo UI installation. However I use Nuget in my examples as people appreciate the convenience - and rightfully so.

2. I'm not sure that it would "reduce" code by any amount. I think the broader question is "When should I use server wrappers?". The answer is "It Depends". Your comfort with JavaScript and project size among other factors will affect that decision.

Maybe we need a blog post on this? :)
3 Ben Hayat 19 Jul 2012
Hi Burke;

Thanks fr the reply;
On the first question, my concern was more around, if we download from NuGet, would it download the "Licensed" version or "Free" version? That's what I to know, how would NuGet know if the developer needs the "Licenced" or "Free" version?

On the second question, yes I think a "Strategy" blog would help for folks to decide:
Should it be done via WebAPI and Standard Kendo Widgets or Should they use MVC with wrappers. Since these are new technologies coming up.

Thank you in advance again!
..Ben
4 Burke 23 Jul 2012
@Ben

1. The open source license is GPLv3. The NuGet package is a convenience for people testing and trying out Kendo UI. Even in the event that the OS version is being used, it should really be downloaded from the Kendo UI site. Unfortunately, I can't provide guidance on whether projects fall into that category or not.

2. I'll see if I can talk Todd into doing this. :)
5 Ben Hayat 24 Jul 2012
Even in the event that the OS version is being used, it should really be downloaded from the Kendo UI site.

Thanks Burk; That answers my question.
..Ben
6 Cory 25 Jul 2012
I'd be interested to see you continue this post to include serverSorting and serverFiltering, since both require non-primitive types. From what I can tell, this isn't trivial using Web API. If you already have an example please point me in the direction of the post.
7 Dan 26 Jul 2012
I'd like to second Cory's request. I went through the example and then tried to add sorting, eventually moving to server sorting as the client-side is fairly useless in multi-page grid. It seems like a more complicated thing to pull off and worth a mention.
8 Burke 09 Aug 2012
Hey @Cory and @Dan

Thanks for your suggestion. I agreed with you and thought it would make an excellent example that many could benefit from.

Ask and you shall receive! :)

Ask Kendo UI - Server Sorting With WebAPI
9 Mau 20 Sep 2012
Hi Burke, great tuto, thanks for sharing.
In my project I don't use WebApi's but regular JSON controllers. Although these work great with client paged grids, they don't seem to work with your code.
Why is that happening? See below for screenshots attached.
Thanks again.

http://grab.by/gdwI
http://grab.by/gdwO
10 Burke 20 Sep 2012
@Mau

What's not working for you? The server-side paging? Your JSON results look legit to me upon first glance.

Could you provide some more info?
11 Mau 20 Sep 2012
@Burke, Thanks for the quick reply.

It is a MVC 3application which usually fills Kendo grids with JSON result from the controller.

The client side paging is working ok, but the server side isn't.

I cannot use EF like you do in your example, since the fields of the query are totally customizable, instead I serialize DataTables with NewtonSoft's Json.NET

Hope this can give you more clues.
12 Mau 21 Sep 2012
For further information, here is the js and c# code
http://pastebin.com/a2Kwjf0q
http://pastebin.com/75ggpWdV
13 Mau 21 Sep 2012
I missed this one: http://pastebin.com/vbXzNvEx
14 Mau 21 Sep 2012
Finally, I got it working!!! The schema was misplaced.
Thanks for the effort though.
15 Congero 19 Oct 2012
Maybe I'm looking in the wrong place but do you have a similar walkthrough using the Razor syntax
16 Manik Mittal 08 Nov 2012
Hi,

I have tried to add the library package reference using the nuget. but it comes up with old version. On my windows and project I already have kendoui version 2012.2.913.340 but if i run the nuget to add the library package reference, it comes up with 2012.2.710 and the intellisense for jQuery is still not working. I am missing something?

Thanks for your support
17 Mel Liu 10 Nov 2012
Hi @Ben!
How change request parameter names, for example:
CHANGE
xxx.com.query?take=12&skip=0&page=1&pageSize=12
TO
xxx.com.query?_take=12&_skip=0&_page=1&_pageSize=12
18 Burke 12 Nov 2012
@Mel

I'm not sure why you would want to prefix everything with an underscore, but there are always valid use cases that I'm not aware of. You can always modify the parameters by passing them through the parameterMap.

dataSource: {

    transport: {

        read: "customers"

    }.

    parameterMap: function(options, operation) {

        // return a custom parameter object

        return {

            _skip: options.skip,

            _take: options.take,

            _page: options.page,

            _pageSize: options.pageSize

       };

    }

}
19 micheal frias 12 Dec 2012
This post i really great The information you 've post is rally good .Nice job thanks for sharing this.

Comment

Your name Click to add
Email (optional) Click to add
Website (optional) Click to add

Comment

.NET Developer Tools DevTools

Hybrid Mobile Development Icenium

HTML5 / JavaScript Development Kendo UI

Testing Tools TestStudio

Web Presence Platform Sitefinity CMS

Agile Project Management TeamPulse

Contact us

About Telerik

Blogs