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 un-needed 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
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
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
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">
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 similiar 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.
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
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
<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.
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.