Cascading Country / State Dropdowns: A Study in DotNetNuke 7 WebAPI Services and Ajax

Building the Services

Building a service starts out in much the same way we build a module. We create a library project in Visual Studio (required version of .NET framework is 4.0), include references, and build to the DNN bin folder.

Create the Controller and Actions

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
using DotNetNuke.Common.Lists;
using DotNetNuke.Web.Api;

namespace DNNuclear.DNN.ListServices.Services.Controllers
{
    public class ListsController : DnnApiController
    {
        [HttpGet] // GET: /Countries/
        [ActionName("countries")]
        [AllowAnonymous]
        public List GetCountryList()
        {
            DotNetNuke.Common.Lists.ListController lc = new DotNetNuke.Common.Lists.ListController();
            List leCountries = lc.GetListEntryInfoItems("Country", "", base.PortalSettings.PortalId).ToList();
            return leCountries.Select(x => new NameValueItem { Text = x.Text, Value = x.Value }).ToList();
        }

        [HttpGet] // GET: /Regions/{code}
        [ActionName("regions")]
        [AllowAnonymous]
        public List GetRegionList(string code)
        {
            DotNetNuke.Common.Lists.ListController lc = new DotNetNuke.Common.Lists.ListController();
            List leRegions = lc.GetListEntryInfoItems("Region", "Country." + code, base.PortalSettings.PortalId).ToList();
            return leRegions.Select(x => new NameValueItem { Text = x.Text, Value = x.Value }).ToList();
        }

        public class NameValueItem
        {
            public string Value { get; set; }
            public string Text { get; set; }
        }
    }
}

WebAPI requires that the name of all controllers end with the word Controller hence the name of our class ListsController which inherits DnnApiController. I decorated the methods with [HttpGet] to indicate that it is responding to GET requests. The ActionName indicates the action in the route url. The AllowAnonymous attribute is part of the framework security. This method requires no authentication and can be accessed by any application external or internal. I won't go further on the security aspects of the services framework because it is beyond the scope of this basic tutorial.

The code itself is using the List API to get the collection of items to create a generic list of the NameValueItem class. WebAPI will automatically convert any POCO (Plain Old C# Class) and output it as Json (or Xml) based on the content disposition.

Create the Routes

using System;
using DotNetNuke.Web.Api;

namespace DNNuclear.DNN.ListServices.Services
{
    public class DNNListServices : IServiceRouteMapper
    {
        const string moduleFolderName = "DNNListServices";

        public void RegisterRoutes(IMapRoute routeManager)
        {
            routeManager.MapHttpRoute(moduleFolderName, "list", "{controller}/{action}",
                    new[] { "DNNuclear.DNN.ListServices.Services.Controllers" });

            routeManager.MapHttpRoute(moduleFolderName, "sublist", "{controller}/{action}/{code}",
                    new[] { "DNNuclear.DNN.ListServices.Services.Controllers" });
        }
    }
}

Here is a break down of each of the parameters passed to IMapRoute.MapHttpRoute:

• moduleFolderName - set to the constant: This parameter is unique to DNN and should be a name unique to your module/service, and will typically match the name of the DesktopModules folder in which your module is installed. It is important to use a name unique to your service to avoid routing conflicts with other services that may be installed.
• "list" - string routeName: A name for your route. This makes up part of the total route name when routes are registered in ASP.Net. The combination of moduleFolderName and routeName must always be unique.
• "{controller}/{action}" - string url: Standard WebAPI parameter that defines the unique characteristics of your route.
• "new [] {"MyServices"} = string[] namespaces: Unique to DNN, this is an array of namespaces to search for controllers for this route. The parameter helps prevent conflict between services built by different developers.

With the two routes defined, our two service endpoints examples will be the following:

• /DesktopModules/DNNListServices/api/lists/countries
• /DesktopModules/DNNListServices/api/lists/regions/US

Therefore the service endpoint consists of DesktopModules / [ModuleName] / api / [ControllerName] / [Action] / [CountryCode(for Region)]

The Ajax Client

Now that our REST services are ready, we are going to build a client to consume the services. The client will consist of two select lists - one for country and the other for state. We are going to use a jQuery component called jCombo that hooks up both the ajax loading AND the dependency loading (making one dropdown load based on the value of the other).

The Html

<div class="dnnForm" id="dnnucForm_JComboTest">
<fieldset>
<div class="dnnFormItem dnnFormShort">
  <div><label><span id="lblCountry">Country:</span></label></div>
  <select name="ddlCountry" id="ddlCountry"></select>
</div>
<div class="dnnFormItem dnnFormShort">
<div><label><span id="lblRegion_lblNoHelpLabel">State:</span></label></div>
<select name="ddlState" id="ddlState"></select>
</div>
</fieldset>
</div>

I added an HTML module to a test page and added the following html to it to create two empty select lists named: ddlCountry and ddlState.

The Javascript

Next I added the following javascript to the Header of the HTML module (Module Settings>Advanced Settings>Header)

<script id="aJQCombo" type="text/javascript" src="/Portals/0/Scripts/jquery.jCombo.js"></script>
<script type="text/javascript">
    $(document).ready(function () {
        bindSelectLists();
    });

    function bindSelectLists() {
        var basePath = "/DesktopModules/DNNListServices/";
        $("#ddlCountry").jCombo(basePath + "api/lists/countries", { selected_value : 'US' } );

        $("#ddlState").jCombo(basePath + "api/lists/regions/", { 
			        parent: "#ddlCountry"
		        });
    }
</script>

Be sure to drop the jquery.jCombo.js into the correct folder on the server. I chose to put it in a scripts folder under my portal root.

The script simply initializes the select lists as jCombo components passing the path of our GET json service to the constructor. Notice the State list gets another parameter called 'parent'. jCombo will create an event on change of the parent dropdown which will take the value of the parent's selected item and add it to the GET url in the first parameter of the child dropdown. So if I select 'US' as the country, it will create an ajax call for the state list as basePath + "api/lists/regions/' + 'US' -- which matches our route for the region lookup with country code.