DotNetNuke Widgets Guide (Part 3 of 4)

Continuing my series on DotNetNuke Widgets, here is Part 3 where I provide insights into how you can develop your own Widgets for DotNetNuke. If you haven’t already done so, read Part 1 (overview of DotNetNuke Widgets) and Part 2 (DotNetNuke Widgets reference) to better understand the concepts explored in this post. Let’s get started.

Widgets are located in two places: ~/Resources/Widgets/DNN for Core Widgets and ~/Resources/Widgets/User/<CompanyName> for user Widgets. The Widget file names are <WidgetName>.js for Core Widgets and <CompanyName>.Widgets.<WidgetName>.js for user Widgets.

Let’s walk through the three basic sections of code that constitute a Widget:

Namespace, Inheritance and Constructor

Using the ASP.NET AJAX library, we register the namespace for our widget and define its inheritance from the BaseWidget class. Finally, we define the constructor.

Type.registerNamespace("YourCompany.Widgets");
YourCompany.Widgets.SampleWidget.inheritsFrom(DotNetNuke.UI.WebControls.Widgets.BaseWidget);
YourCompany.Widgets.SampleWidget = function(widget)
{
    YourCompany.Widgets.SampleWidget.initializeBase(this, [widget]);
}

Render Method

Every Widget must implement the render() method. Typically, this method will follow a pattern consisting of two steps: (1) enumerate the parameters specified in the Widget declaration (i.e. <param> elements) and assign them to local variables, (2) do some processing based on the parameters and call the render() method. When you call the render() method in Step 2, you pass in a DOM element that you create. The framework will replace the <object> element with which the Widget was defined with your DOM element and assign it the original ID that the <object> element was given. What your code does during Step #2 in order to populate the contents of the DOM element you create or manipulate other elements of the page is entirely up to you. Your Widget has access to any DOM element and can make calls to any other custom scripts, ASP.NET AJAX library functions, jQuery plugins etc.

YourCompany.Widgets.SampleWidget.prototype =
{
   render:
   function()
   {
      var params = this._widget.childNodes;
      if (params != null)
      {
          // Do something
      }

      var div = document.createElement("div");
      // Do some work here to add content to the div
      YourCompany.Widgets.SampleWidget.callBaseMethod(this, "render", [div]);
   }
}

Registration and Rendering

The last thing you have to do in your Widget is to register its class and tell the Widget framework that it can render all instances of your Widget present on the page.

YourCompany.Widgets.SampleWidget.registerClass("YourCompany.Widgets.SampleWidget", DotNetNuke.UI.WebControls.Widgets.BaseWidget);
DotNetNuke.UI.WebControls.Widgets.renderWidgetType("YourCompany.Widgets.SampleWidget");

The above is all you need in order to create the basic scaffolding for a Widget. Add your custom code, save the file following the expected name and location conventions and you can start using your Widget right away (you’ll have to do some more work to package the Widget if you want it to be installable using the DotNetNuke Extension Wizard).

If you would like to see the code for a functional user Widget, you can download and install the Module Print Widget. The module displays a dropdown that allows a page viewer to select from a list of modules on the page and print any single module thus eliminating the need to display a print icon on every module.

Stay tuned for the last part in this series where I take you step-by-step through the process of building a Product Catalog Widget that makes use of third-party jQuery plugins, injects stylesheets dynamically and renders a nice UI using the jQuery UI extensions.