Getting Started with the Infragistics jQuery Combo

One of the neat components bundled in the NetAdvantage for jQuery pack is definitely the IG combo box. This component is all about enabling the user to efficiently select data from a set of given options , elusively similar to what a regular <select> tag does in plain HTML. It even looks like a regular <select> tag ! This is where, however, all similarities end – with just a few of the myriad of options available for the IG Combo , you can turn it into a data-selecting powerhouse. This blog will walk you through setting up an igCombo widget and tailoring its functionality to your needs. There's also an example project which you may download and take a look at.

Let’s get on with it !

Preparation

Our IG Combo box can be added to either a normal web application or an ASP.NET MVC project with equal ease. No matter the type of project you are using, you will need to add a set of required CSS and JavaScript files to it in order to make the control function properly.

Required Files

The files seen in the Scripts/ folder can be taken from the folder where you installed your Infragistics products – just navigate to it, then open the jQuery/js folder and copy the needed files. The two jquery-related scripts should already be present in your project but if they are not – you can grab the versions you see on the image from the jQuery/demos/scripts folder.

As for the Content/ folder, it should contain resources such as images, audio, video and styles related to your site. This is where you will need to put the css styles required to properly visualize the beauty of the IG Combo. Highlighted folders can be found in the jQuery/themes folder – so just copy that in your Content/ folder.

N.B. The following step is only helpful in the case where a MVC project is used – it will add the Infragistics Helper to your project which will let you manipulate components with ease due to IntelliSense support.

Add Reference

Right-click on your MVC project and select “Add Reference”. Next, browse to the jQuery/MVC folder and open whichever folder reflects the version of MVC you’re using e.g. MVC3. Select the Infragistics.Web.Mvc DLL and hit okay. You’re all set !

Now it’s time for us to…

…Make It Work

With all the required files added, it’s time to actually see the component in action ! Add a reference to the previously added files like so:

Plain HTML

   1: <link href="Content/min/ig/jquery.ui.custom.min.css" rel="stylesheet" type="text/css" />
   2: <link href="Content/base/ig.ui.min.css" rel="stylesheet" type="text/css" />
   3: <script src="Scripts/jquery-1.4.4.min.js" type="text/javascript"></script>
   4: <script src="Scripts/jquery-ui.min.js" type="text/javascript"></script>
   5: <script src="Scripts/ig.util.min.js" type="text/javascript"></script>
   6: <script src="Scripts/ig.dataSource.min.js" type="text/javascript"></script>
   7: <script src="Scripts/ig.ui.combo.min.js" type="text/javascript"></script>

Razor syntax

   1: <link href="@Url.Content("~/Content/min/ig/jquery.ui.custom.min.css")" rel="stylesheet" type="text/css" />
   2: <link href="@Url.Content("~/Content/base/ig.ui.min.css")" rel="stylesheet" type="text/css" />
   3: <script src="@Url.Content("~/Scripts/jquery-1.4.4.min.js")" type="text/javascript"></script>
   4: <script src="@Url.Content("~/Scripts/jquery-ui.min.js")" type="text/javascript"></script>
   5: <script src="@Url.Content("~/Scripts/ig.util.min.js")" type="text/javascript"></script>
   6: <script src="@Url.Content("~/Scripts/ig.dataSource.min.js")" type="text/javascript"></script>
   7: <script src="@Url.Content("~/Scripts/ig.ui.combo.min.js")" type="text/javascript"></script>

Once the references have been added, what’s left is to create a combo box and get to play with it ! If you’re using a standard web application, you will need an existing element which will act as a base for the combo box – a list of elements that the combo will happily bind to can be seen here.  Additionally you will also need some form of a data source to feed to the combo box.  A simple array of strings is used in this example.

Plain HTML

   1: <div id="combo_target"></div>
   2:     <script type="text/javascript">
   3:         $(document).ready(function () {
   4:             var items = ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"];
   5:             $("#combo_target").igCombo({
   6:                 width: 200,
   7:                 autoComplete: false,
   8:                 dataSource: items
   9:             });
  10:         });
  11:     </script>

The same effect can be achieved in a MVC setup as well. First, this is what your controller should look like:

HomeController.cs

   1: using System;
   2: using System.Collections.Generic;
   3: using System.Linq;
   4: using System.Web;
   5: using System.Web.Mvc;
   6:  
   7:  
   8: namespace MvcApplication1.Controllers
   9: {
  10:     public class HomeController : Controller
  11:     {
  12:         public ActionResult Sample()
  13:         {
  14:             List<string> options = new List<string>();
  15:             options.Add("Item 1");
  16:             options.Add("Item 2");
  17:             options.Add("Item 3");
  18:             options.Add("Item 4");
  19:             return View(options.AsQueryable());
  20:         }
  21:     }
  22: }

Then in a view of your choice, you initialize the combo box like this:

   1: @Html.Infragistics().Combo().DataSource(this.Model as IQueryable<string>).Render()

Two things to note in the code above – first, .Render() is needed in order to be able to see the control. Second, notice how we have no underlying HTML element – the IG Helper takes care of that. An element will automatically get created and the combo box will be build on top of it – in this case the created div element will have an id of “Combo1”, and each subsequent combo box added in this manner will increment that index by one.

Now that you know how to create an IG Combo ( see, it wasn’t too hard, was it? ), it’s time to find out what you can do with it, so let’s get right into…

 

…The Options

Adding even more functionality to your igCombo widgets can be done in a whim – next up is a small example of how to add auto-completion, as well as highlighting items that match a certain search criteria. And if that isn’t enough, we’ll also make it so the user can select more than one item from the list, with the aid of checkboxes or by holding down the control key.

It all comes down to these few lines of code:

Plain HTML

   1: $("#combo_target").igCombo({
   2:                 width: 250,
   3:                 multiSelection: "onWithCheckboxes",
   4:                 autoComplete: true
   5: });

Razor syntax

   1: @Html.Infragistics().Combo()
   2: .AutoComplete(true)
   3: .MultiSelection(ComboMultiSelection.OnWithCheckboxes)
   4: .Render()

Yup, that’s all it takes ! And this is barely scratching the surface of what you can do – for a full list of options, load up the documentation where you can see all the possible tweaks, along with examples. ASP.NET MVC users may additionally want to check the exclusive IG Helper docs. Now let’s move on to…

…The Events

The NetAdvantage for jQuery Combo component hosts a handful of events which you can freely assign your own custom functionality to. This is done entirely through javascript and does not differ based on the type of project you’re using.

First, familiarize yourself with the events available by going to this page. Once you’ve chosen a particular event you wish to bind a function to, you can do so in the following manner:

   1: $("#combo_target").igCombo({
   2:                 width: 200,
   3:                 autoComplete: false,
   4:                 selectionChanged: function (evt, ui) {
   5:                     alert(ui.items[0].value);
   6:                 }
   7: });

This is all fine but there is also the case where you might need to bind the event in post-initialization period. jQuery of course helps by letting you do this:

   1: $("#combo_target").bind("igcomboselectionchanged", function (evt, ui) {
   2:                 alert(ui.items[0].value);
   3: });

Pay attention to the name of the event you’re binding to – it’s different than before ! All NetAdvantage for jQuery controls’ events follow the standard jQuery naming convention of componentnameeventname.This might be confusing since at some point in time you will need to utilize both ways of event binding and therefore risk getting tangled up in different naming conventions. Here’s a little trick you can use to late-bind events to IG jQuery components:

   1: $("#combo_target").igCombo("option", "selectionChanged", function (evt, ui) {
   2:                 alert(ui.items[0].value);
   3: });

Notice how you’re setting an option, just like before. But instead of an actual “option”, you use the event name just like it’s listed on the “Events” page in the API docs. For a variable, you pass your custom logic.

 

Final Words

Hopefully by now, you have gotten a good understanding on how to set up an Infragistics jQuery Combo control, either in a normal web application or in a MVC project via the ASP.NET MVC HTML Helper. We also went through event binding and enhancing functionality on the control by configuring its options

 

Click here and download a sample solution which contains the topics covered in this blog post.

You can download a trial version of NetAdvantage for jQuery from this page.

If you would like to see some samples, please visit this page.


Attachment: IGCombo.zip

Add a Comment

Please Login or Register to add a comment.