Creating a DotNetNuke Skin Object

A few weeks ago Tom Kraak of Seablick Consulting made a blog post regarding modifications to the core Breadcrumb skin object to prevent the last page in the tree from rendering as a link. I created two different solutions for him, the first was simply a modification to the core breadcrumb object and was not necessarily the best solution. The second solution I provided was the creation of a custom skin object, based on the core, but isolated so that it will not be prone to issue with an upgrade. This tutorial is the promised "overview" of how to create a skin object. I will not discuss the technical aspect of the modifications that were made to the breadcrumb, but just a general overview of what you actually have to do to create a new skin object.

What is a Skin Object?

Before I start with the technical process of creating a skin object, I thought it would be a good idea to quickly explain what a SkinObject is and why you might use one. SkinObjects are simply user controls that are designed to run at the skin level. These are items that are configured via properties that are set in the skin file and will be rendered at all times that your skin is displayed. Examples of skin objects include the login and register links, the breadcrumb, the logo, the menu and more.

Where to Start?

The hard part is determining the best way to start the project. I personally started with a standard DNN module project using the compiled module template. I then proceeded to clear out all unneeded files, including the default .dnn file as with a SkinObject you must follow a different format to complete the installation. There are other methods of creating the starting project, however, I like to keep things simple.

Once I cleared out the project I added a new WebUserControl to the page, this user control will be your interface for the breadcrumb. After adding this to the project, I switched to the source view and added the following import statement

Imports DotNetNuke.UI.Skins

This imports statement prepares us for the next step which is ensuring that our WebUserControl inherits from the proper base control. To validate this I modified the Partial Class declaration to be the following. Be sure that MyClass is the name of your user control that you created earlier.

Partial  Class MyClass
     Inherits DotNetNuke.UI.Skins.SkinObjectBase

Now that we have this control created you can continue to implement any and all logic needed on this control. You can define public properties which will be the various configuration elements that users can set when adding your control to a skin. For an example of how a SkinObject is typically coded, you may look at any of the DNN Core skin objects which can be found in the /Admin/Skins folder of your DNN installation.

The DNN File

The most complicated part when I was working to create my first custom SkinObject was determining how to structure my .dnn file. Below is an example of the .dnn file that is included with my SCBreadbrumb Object that was created for Tom.

<?xml version="1.0" encoding="utf-8" ?>
<dotnetnuke version="2.0" type="SkinObject">
  <folders>
    <folder>
      <name>SCBreadcrumb</name>
      <modules>
        <module>
          <controls>
            <control>
              <key>SCBreadcrumb</key>
              <src>SCBreadcrumb.ascx</src>
              <type>SkinObject</type>
            </control>
          </controls>
        </module>
      </modules>
      <files>
        <file>
          <name>SCBreadcrumb.ascx</name>
        </file>
        <file>
          <name>Seablick.SkinObjects.SCBreadcrumb.dll</name>
        </file>
      </files>
    </folder>
  </folders>
</dotnetnuke>

The first item you will be concerned with is the Folder Name value. This value is the name of the folder that your module will reside in. Your SkinObject WILL reside in the DesktopModules folder, this is the name of that folder. In my example, the object was placed in the SCBreadbcrumb folder. The second item of concern is the "Control" section. This is of a similar format to that of a DNN module, the key difference here is that the "Key" is actually the TOKEN that will be used by users working with.HTML based skins. So a key of SCBreadcrumb creates a token of [SCBreadcrumb]. The src is the path to the control, and the type identifies it as a SkinObject.

The final portion of the .dnn file is your file listing, this is just like a DNN module where you must list ALL files that are to be installed.

Packaging/Installing

The packaging and installation rules for SkinObjects are the same as with any standard module. You create a .zip file with ALL files included. Then simply "Install new module" via the Module Definitions page. Once installed you must view the "[SkinObjects]" module via "Module Definitions" to actually see the installed module.

Using the Object

The final step is actually modifying your skin to use the new control. Working with the skin file as a .ascx control you simply perform the following two steps. First, you add the register tag to the top of the skin.

<%@ Register TagPrefix="dnn" TagName="SCBreadcrumb" Src="~/DesktopModules/SCBreadcrumb/SCBreadcrumb.ascx" %>

Obviously you will correct the src and tag name values to match that of your control, then simply place a control declaration anywhere else on the skin to actually display your control.

<dnn:SCBreadcrumb runat="server" id="dnnBreadcrumb" />

Be sure when adding this control declaration that you set any needed properties for your control. This is all that is needed to use a custom skin object.

Conclusion

This article was designed to be a quick overview of how to create a new custom skin object. I hope that you were able to find the information that you needed if not please use my forms to ask for assistance and I will help where I can. Please feel free to share any comments below.