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
or
Install-Package jQueryUIHelpers.Mvc4
or
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.
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):
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="8/12/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):
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 :)