How to use Telerik to speed up your Wisej.NET development

by Jon Hilton

Wisej.NET ships with a large number of pre-built controls for you to use in your web applications, covering almost every requirement you can think of (taking user input, presenting data etc.)

But what if you want to take it up a notch and show your data in more advanced ways, perhaps offer your users themes and have everything in your web app change based on the chosen theme?

Requirements like these can soon ramp up, and before you know it you're having to make a lot of tweaks to the built-in controls to make them behave the way you want them to.

But there is another option…

Component Libraries have a long history in .NET Development.

These handy libraries give you a significant number of battle-tested, pre-built components which you can drop into your web applications, and the good news is Wisej.NET has support for all the major component vendors.

Let's see how to get up and running with one popular component library - Telerik's Kendo UI.

Getting Started

You can bring Kendo support to your Wisej.NET app via the official NuGet package, via the command line:

dotnet add package Wisej-3-Kendo

Or the NuGet GUI:

In the case that the Kendo controls aren't automatically added to the toolbox after adding the NuGet package, you can follow the instructions below:

• Right-click the toolbox and select Add Tab

• Call the new tab something useful (like Telerik, or Keno)

• Right-click the new tab then select Choose Items

• Browse to your project's bin folder and select the dll called Wisej.Web.Ext.Kendo.dll

• Click OK to add the items to the toolbox

Configuration

When you add the NuGet package to your project you should find you now have a file called Wisej.Web.Ext.Kendo.json in your solution.

This controls how your Wisej.NET project interacts with the Kendo library, and includes options for the theme you want to use, plus the source of the components (it defaults to CDN).

For our purposes we can leave the options set to their default values.

But should you want to serve the Kendo packages from your project instead, you can create a folder called Kendo then change the source to Local in this JSON file.

Using Kendo Controls In WiseJ.NET

At this point we should be able to drag and drop any of the Kendo components onto a page in our Wisej.NET application.

Let's start with a really simple (if slightly niche!) control, kendoBarcode.

It might seem like a random choice for learning how Kendo and Wisej.NET work together but the barcode component has the significant benefit of being small and relatively simple, so easy to work with as we explore the various ways we can interact with the controls from a Wisej.NET application.

When you drop a Kendo control onto your Wisej.NET control/page/form, you should see it rendered in the WYSIWYG preview:

So far so good, but how can we interact with the configuration of the control? Let's jump into the code and see what we've got:

The primary mechanism for controlling the Kendo controls is via the dynamic Options property.

For example, to set the value of this barcode control we can set its Value via Options in code, like this:

public partial class KendoExamples : Wisej.Web.UserControl
{
    public KendoExamples()
    {
        InitializeComponent();

        this.kendoBarcode1.Options.Value = "1928374";
    }
}

Now if you run this in the browser it's not immediately obvious whether it's working, mainly because the text for the barcode isn't shown automatically (just the barcode).

Taking a quick look at the Telerik docs for the barcode component API, we can see an option to display the barcode value as text via the text.visible property.

One thing to watch out for, when setting a property more than one level deep (as in this case, where visible is not a top level property), you'll need to call Update() for the changed property to take effect.

Here's how I managed to display the barcode value as text in the barcode component.

public partial class KendoExamples : Wisej.Web.UserControl
{
    public KendoExamples()
    {
        InitializeComponent();

        this.kendoBarcode1.Options.value = "1928374";
        this.kendoBarcode1.Options.text = new { visible = true };
        this.kendoBarcode1.Update();          
    }
}

With that, we can now see everything is working (when we view this in the browser).

Interacting with third party controls via their properties is one way to get this working, another is to use methods instead.

Any methods which are exposed via the API for the component can be accessed via the Instance property.

For example, we can set the barcode's value using a method, like this:

this.kendoBarcode1.Instance.value("567354");

It's also possible to call that method asynchronously, using the await keyword. Here for example is how we might await an operation to export the barcode to a PDF:

var result = await this.kendoBarcode1.Instance.exportPDFAsync();

In this case result will be a dataUrl for the generated PDF.

Alternatively, you can provide a callback:

kendoBarcode1.Instance.exportPDF((Action<dynamic>)(r =>
{
    AlertBox.Show(r);
}));

Here we're passing a callback which will be invoked when exportPDF completes.

Effectively this produces the exact same result as using the await approach above.

Note I've explicitly cast the lambda callback expression to be of type Action<dynamic>.

Without this we run into a compile error:

An anonymous function or method group cannot be used as a constituent value of a dynamically bound operation

Because Instance is dynamic the compiler can't infer the types involved when we invoke the exportPDF method. The explicit cast indicates that we expect a dynamic object to be passed to the callback when it's invoked.

Attaching to client-side events

So far we've seen how to dsiplay Telerik components on the page and interact with their properties and methods.

But what about reacting to events.

For example, one of the Kendo controls is a rating control.

https://docs.telerik.com/kendo-ui/controls/rating/overview#kendo-ui-for-jquery-rating-overview

Logically you'd want to be able to run logic when a rating is selected.

For that we can attach a handler to any events exposed by the control.

To figure out which events are available we can consult the official Telerik documentation.

Here's a link to the API for the Rating Control:

Configuration, methods and events of Kendo UI Rating - Kendo UI for jQuery

There you can see a number of events listed. We're interested in the change event.

We can attach to that via the dynamic Instance object if we prefix the event name (change) with on:

public partial class KendoExamples : Wisej.Web.UserControl
{
    public KendoExamples()
    {
        InitializeComponent();
        
        this.kendoRating1.Instance.onChange += new WidgetEventHandler(kendoRating1_WidgetEvent);                     
    }

    private void kendoRating1_WidgetEvent(object sender, WidgetEventArgs e)
    {
        AlertBox.Show(e.Data.newValue.ToString());    
    }
}

This assigns an instance of WidgetEventHandler (which points to kendoRating1_WidgetEvent method) to the change event.

Again we don't have any explicit types to work with here as Instance is a dynamic object.

e.Data is also dynamic in this case (Data on WidgetEventArgs points to a dynamic object).

As before, we can check the official API docs to see what's available. in this case we should have access to a newValue property.

change - API Reference - Kendo UI Rating - Kendo UI for jQuery

With that, when a rating is selected, an AlertBox pops up which shows the selected rating.

Putting it all together

Finally, let's pull all these pieces together with a more realistic requirement.

Let's say we want to show the movie data we've explored in previous articles, but using Telerik's controls to show the list of movies.

Previously we used the built-in dataGridView to show the list of movies:

Let's try using Telerik's DataGrid control instead:

The first step is simple enough, to drag and drop an instance of kendoGrid onto a page. But where to go from there?

If we take a look at the Telerik docs we can see a dataSource property for binding the grid to data:

jQuery Grid Documentation - Local Data - Kendo UI for jQuery

We can point that to our existing movie data source:

public partial class TelerikGrid : Wisej.Web.UserControl
{
    public TelerikGrid()
    {
        InitializeComponent();           
    }       

    private async void TelerikGrid_Load(object sender, EventArgs e)
    {
        this.kendoGrid1.Options.dataSource = await new MovieService().GetMovies();
    }
}

Just like that, we have a Telerik grid showing movies.

We can now switch on other grid features as we wish. Let's make it sortable:

private async void TelerikGrid_Load(object sender, EventArgs e)
{
    this.kendoGrid1.Options.sortable = true;
    this.kendoGrid1.Options.dataSource = await new MovieService().GetMovies();
}

Now we can click on any of the column headings to sort the data by that column.

One of the big advantages of using a component from a vendor like this is how much quicker it has to handle typical requirements.

For example, we can easily enable filtering by setting filterable to true.

private async void TelerikGrid_Load(object sender, EventArgs e)
{             
    this.kendoGrid1.Options.sortable = true;
    this.kendoGrid1.Options.filterable = true;
    this.kendoGrid1.Options.dataSource = await new MovieService().GetMovies();
}

We can go a step further and enable useful functionality like exporting to PDF too, still just by using the Options property to toggle specific features on (or off).

private async void TelerikGrid_Load(object sender, EventArgs e)
{
    var toolbar = new[] { "pdf" };
    this.kendoGrid1.Options.toolbar = toolbar;
    
    ...
    
    this.kendoGrid1.Options.dataSource = await new MovieService().GetMovies();
}

Here I've declared an array with a single entry (the string "pdf"). This is enough to make an "Export to PDF" button appear above the grid. When we click that the grid is exported to PDF and the PDF downloaded via the user's browser.

In Summary

There are significant time-savings to be had if you can use pre-built components to build your Wisej.NET app.

Wisej.NET has support for Telerik's Kendo component library and you can easily drag and drop Kendo components into your Wisej.NET controls/pages.

The Options property gives you an easy way to set the component's properties. Just remember to call Update if you set properties more than one level deep.

Finally, Instance gives you a handy way to invoke methods on the Kendo components, with support for Async operations as well.

Next Steps

Keen to start using Kendo UI controls in your Wisej.NET projects? Find out more about the Kendo premium extension (as well as a number of other premium extensions for other component vendors) over in the official docs.