jQuery UI Helpers - Getting Started

Installation

You can install jQuery UI Helpers from NuGet either with the Package Manager Console or using the GUI. In the console exectute one of the following depending on you project type:

Install-Package jQueryUIHelpers.Mvc5

Install-Package jQueryUIHelpers.Mvc4

Install-Package jQueryUIHelpers.Mvc3

The installer adds a reference to the JQueryUIHelpers.dll. It copies the jquery-ui.unobtrusive-x.y.z.js and jquery-ui.unobtrusive-x.y.z.min.js JavaScript files into the Scripts folder and adds them to the project. Finally it registers the JQueryUIHelpers namespace into the Razor section of the web.config file in the Views folder. This makes the helpers available in Razor views (you might need to compile the project or reopen open views).

If you use the ASPX view engine you should register the namespace by hand.

Script and Style References

An ASP.NET MVC3 or MVC4 project comes with a jQuery UI style, located in /Content/themes/base. MVC5 projects do not include jQuery UI by default but it will be installed automatically when you install jQuery UI Helpers. You can use the default style or you can create your customized one using the jQuery UI Theme Roller.

MVC 4 / MVC 5

In the BundleConfig file create a new bundle for the jquery-ui.unobtrusive-x.y.z.js. It is also possible to add this to the jQuery UI bundle so it will always be included when jQuery UI is referenced. The following example demonstrates this.

            bundles.Add(new ScriptBundle("~/bundles/jqueryui").Include(
                        "~/Scripts/jquery-ui-{version}.js",
                        "~/Scripts/jquery-ui.unobtrusive-{version}.js"));

Make sure there is also a bundle with the required jQuery UI CSS files. The example below shows how to create one that uses only the datepicker, but all other CSS files can be included in the list.

                bundles.Add(new StyleBundle("~/Content/themes/base/css").Include(
                        "~/Content/themes/base/jquery.ui.core.css",
                        "~/Content/themes/base/jquery.ui.datepicker.css",
                        "~/Content/themes/base/jquery.ui.theme.css"));

Render the bundles on the layout page or the views that need them. Add the jQuery UI CSS files like so (in MVC5 projects you also have to define the bundle in BundleConfig):

@Styles.Render("~/Content/css")
@Styles.Render("~/Content/themes/base/css")

And the JavaScript files:

@Scripts.Render("~/bundles/jquery")
@Scripts.Render("~/bundles/jqueryui")

The bundles will handle the version number automatically so you do not have to worry about them when upgrading packages.

If you use client side validation include the validation scripts before the jQuery UI Helpers script. More info.

@Scripts.Render("~/bundles/jquery")
@Scripts.Render("~/bundles/jqueryval")
@Scripts.Render("~/bundles/jqueryui")

MVC 3

Add a reference to the jQuery UI CSS and the jQuery and jQuery UI JavaScript files either on the layout page or the views that use them.

Add a reference to the jquery-ui.unobtrusive-x.y.z.min.js JavaScript file.

The following example uses the MVC 3 built-in theme.

<head>
    <meta charset="utf-8" />
    <title>jQuery UI Helpers - @ViewBag.Title</title>
    <link href="@Url.Content("~/Content/Site.css")" rel="stylesheet" type="text/css" />
    <link href="@Url.Content("~/Content/themes/base/jquery.ui.all.css")" rel="stylesheet" type="text/css" />        
    <script src="@Url.Content("~/Scripts/jquery-1.7.2.min.js")" type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/jquery-ui-1.8.23.min.js")" type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/jquery-ui.unobtrusive-0.5.3.min.js")" type="text/javascript"></script>    
</head>

Do not forget to update the version number in the script reference when you upgrade to a new version of the package. This also applies to the jQuery and jQuery UI references.

First Steps

Now you can start using jQuery UI Helpers!

The library adds a single extension method to the HtmlHelper<TModel> type. This is the JQueryUI<TModel>() method which serves as the entry point of the library. All the widgets are available through it.

The jQuery UI Helpers entry point.

For example you can create a simple Datepicker like this:

<div>
<label for="date">Select a date:</label> @Html.JQueryUI().Datepicker("date")
</div>

This generates the following HTML:

<div>
<label for="date">Select a date:</label> <input data-jqui-dpicker-dateformat="m/d/yy" data-jqui-type="datepicker" id="date" name="date" type="text" value="" />
</div>

And here it is in action (click in the textbox):

Select a date:

Configuration

The previous example created a Datepicker with the default settings. But the jQuery UI widgets have many options to customize their behaviour. The jQuery UI Helpers library supports this with a fluent configuration API.

Let's create another Datepicker.

<div>
<label for="anotherDate">Select another date: </label>
@(Html.JQueryUI().Datepicker("anotherDate").MinDate(DateTime.Today).ShowButtonPanel(true)
.ChangeYear(true).ChangeMonth(true).NumberOfMonths(2))
</div>

This generates the following HTML:

<div>
<label for="anotherDate">Select another date: </label>
<input data-jqui-dpicker-changemonth="True" data-jqui-dpicker-changeyear="True" data-jqui-dpicker-dateformat="m/d/yy" data-jqui-dpicker-mindate="6/25/2022" data-jqui-dpicker-numberofmonths="2" data-jqui-dpicker-showbuttonpanel="True" data-jqui-type="datepicker" id="anotherDate" name="anotherDate" type="text" value="" />
</div>

And here is the datepicker (click in the textbox):

Select another date:

HTML Attributes

Most of the jQuery UI helper methods have overloads with an htmlAttributes parameter. You will notice that while the built-in helpers have two versions (object and IDictionary<string, object>) the jQuery UI helper methods always expect an object type for this attribute. If the methods receive an object that implements IDictionary<string, object> they will use the keys and values to generate the HTML attributes, otherwise they will use the properties of the object.

Next Steps

Use the menu on the top left to read more about the widgets and see them in action.

Watch this demo (with annotations) to see how to enhance a form with jQuery UI and jQuery UI Helpers. This video was recorded in 2012 - the theme selector is no longer supported!

Use NuGet to install jQuery UI Helpers and try it :)