What changed for DNN 5.1 skinning?
Please note that this is targeted at DNN 5.1, not 5.0 (which is slightly different)!
Here are the main changes:
1. A skin is an extension
The special status of skins has changed; a skin is an extension now, just like anything you install to extend DNN.
This has a lot of advantages;
A. We can use one installer for all extensions
(people will have to get used to this, but in the end it will make installing extensions easier)
B. DNN 5 Skins can have a version number.
C. Skins can include a license text, release notes and the author is visible in the admin interface of DNN.
D. You can create packages that install multiple extensions. This means you can package a skin object with a skin. If a skin needs a specific skin object you had to instruct the user to download and install it separately in DNN 4, they can now be installed from one package.
This means a DNN 5 skin needs manifest file, listing all the files in the package, a DNN 5 skin is not a simple zip file anymore. You can still install legacy skins in DNN 5, read more further below.
2. jQuery is included with DNN 5.0.0
There are two ways to get the page to load the jQuery framework.
1. Create a simple module to register the jQuery request and place it on the page. Read this blog post by Joe Brinkman, which shows the necessary code to register the request.
2. Turn on the Widget framework which requires jQuery and will automatically register the jQuery request.
(Menu: Admin > Site Settings > apearence > [v] Enable skin widgets)
These are client side script blocks that can be installed as an extensions and used in skins or modules
Examples: take a look at the Minimal Extropy (the text size buttons) and the Extropy skin.
4. Use Object tags to add skin objects in HTML skins
In DNN 4 skin objects are include in an HTML skin using [TOKENS] and the Skin.xml file.
Since editing XML files is an extra step and you cannot see what attributes are set for a skin object in the HTML source a new way to add skin objects to an HTML skin is included in DNN 5.
The idea is really simple, you use an object tag to include a skin object in an HTML skin and the object tags parameters to set the attributes.
This is a much cleaner and easier solution since HTML developers are using them a lot already.
An example "skin object" inclusion be like this:
As you can see the object tag itself needs a codetype="dotnetnuke/server" attribute so the skin parser knows it is a skin object.
The codebase="LOGIN" attribute will determine what skin object this is, here you use the same string you would use for [Token] inclusion of skin objects (the name of the skin object).
The attributes of the skinobject are set though a
node inside the object tag.
It is simply the attributes name and it's value, add one parameter tag for each attribute.
Please note that bot methods [TOKENS] and
There are two important things to remember:
More Examples: Minimal Extropy skin (the default DNN 5 skin).
5. TEXT skin object
You can add localized text to the skin, and also use token replace in the text you add.
Example: Minimal Extropy skin.
6. You can set the default fallback doctype.
Sets the fallback "Skin Doctype" for webpages. This is used if the Skin does not define the DocType.
This means you can force DNN to use the XHTML doctype, even if the skin does not define the doctype
Menu: Host > Host Settings > Host Details > Fallback Skin Doctype.
All these will be explained further and illustrated with examples, later.
For now I will focus on the main subject, "using legacy skins in DNN 5" and "Converting a legacy skins to a DNN 5 skin".
Using Legacy skins in DNN 5
Do you need a DNN 5 skin for DNN 5?
The answer is NO, you can install legacy skins and containers in DNN 5 and they should work.
For now there are two known restriction.
1. File names inside LEGACY skin / container combined packages are case sensitive
The zip files inside the pack are cases sensitive! The names must be Skins.zip and Containers.zip or installation will fail.
Note: I think this has beeen corrected DNN 5.0.1 (
issue 9030 )
2. Pane ids are case sensitive in DNN 5.0.0
This is not a problem if you add them as HTML tokens and parse the skin: [CONTENTPANE]
But it is if you add them as controls to your HTML or ASCX skin:
These two examples will not be treated the same in DNN 5.0.0.
If you only have the second one in your skin, it will remain empty, since it's not the "ContentPane"
All these are fixed in DNN 5.1
Manage your skin in DNN 5
There 2 major changes in DNN 5 skin management
A. Admin skin uploads no longer possible
In DNN 4 an admin could install skins if the Host would allow him to.
In DNN 5 administrators cannot install skins anymore.
The reason for this is that installing a skin has the same security risks as installing a module (you can include server side script). For this reason installing modules has always been restricted to Host users, the same applies to Skins now.
If you are logged in a Host user, you can still install Portal skins, via: Admin > Extensions > Install Extension Wizard
B. Manage skin pages
Due to the changes mentioned before the location and the functionality of the skin management pages has changed too.
Skin management for Admins
Handeling and parsing skins is done from the Admin > Skins page.
Installing a Admin skin (aonly logged in as host) is done from the Admin > Extensions page
Installing skins / containers in DNN 5.
Install a Host skin, using the extension installer.
A. Login as Host
B. Menu: Host > Extensions
C. Click the "Install extension wizard" link.
D. Browse the skin package.
E. Click "Next"
You will see a warning if you are trying to install a legacy skin
F. Select the "Skin" or "Container" radio button and browse to the package (again).
If you are installing a "Skin & Container combined" package, you should select the Skin radio button.
G: Click "Next" until the skin is installed.
Install a portal skin.
Login as host and use: Admin > Extensions > Install Extension Wizard.
The rest is the same a for Host skins
Install the legacy skin, using copy / ftp.
A. Unzip the skin zip
B. FTP or copy the unzipped skin folder to the "Portals/_default/Skins" folder.
The skin will be installed and visible in the Skin manager, so you can apply it, but it will not be registered as an extension.
Converting a legacy skins to a DNN 5 skin.
The major difference between a legacy and a DNN 5 skin is the Manifest file.
This adds support for skin versioning, install notes, licensing info on install etc.
You can create one yourself or have DNN 5 do it for you; it will also package the skin into a zip file for you.
The Manifest File
In DNN 5 a skin is an extension, it has a manifest file (just like modules already had).
This is the main difference between a legacy (pre 5) and a DNN 5 skin.
The manifest is an XML file, with a .dnn extension.
It contains the attributes and contents of the skin package.
Skin manifest file Example:
This is My Skin
No warrenties and no support
This is the first release of My Skin.
The different nodes and their meaning:
As you can see the manifest contains a Packages node, there can be more then one package node inside the packages node (multi extension packages).
The package node has some attributes for the package, like its name, owner data, license and release notes.
The part can contain multiple tags.
This means you can add multiple components to a package, for instance a skin and a container, or a skin and a skin object.
Every node contains info about a specific component, such as type (Skin / Container), base path (path to install to) and a "list" of included files.
Note: For a container change the type to "Container" (case sensitive!)
This should give you enough information to create your manifest files manually, but you can also use DNN 5 to create the manifest for you.
Use DNN to create your Manifest file
You have to install the legacy skin first if you want DNN to generate the package for you.
Note: ATM there is no support for creating packages with skin and container combined in one file, you will have to unzip the legacy package and install skin and container separately. Then you create DNN 5 package for both of them and combine the two into one package manually (explained later).
There are two ways to install a skin / container (explained above). You can use the extension installer, or copy the skin to the skins folder. If you used the copy method or you upgraded DNN, you will first have to do this:
Create a package from skins after an upgrade or installed using "copy / ftp".
A. Login as Host
B. Menu: Host > Extensions
C. Click the "Create new Extension" link
D. Select skins from the dropdown.
E. Enter the name for the skin; this should be the name of the skin folder you just copied to the skins folder.
F. Enter Friendly name, Description and Version for the skin and click "Next"
G. Enter the "Owner info" and click "Next"
The skin should be registered as an extension.
Now DNN can create your DNN 5 skin package.
Create a DNN 5.0 Package
A. From Menu: Host > Extensions, click the edit icon of the skin package.
B. Enter the package data in the screen and click "update skin"
Do not change the "Skin Package Name" or the wizard will not complete successfully, you can change this later by editing the generated extension package.
C. Click the "Create package" link.
D. Leave the checkboxes as they are and click "Next"
E. In the list under: "Choose Files to include", check if all files are included (they normally should be)
Please note that ATM you can change the folder path here but the wizard will fail if you do.
F. Click "next", review the Manifest file and click "next" again.
G. Enter the name for the Manifest file (you must enter the .dnn extension)
H. Enter the package name (this is the name of the package zip file), you must enter the .zip extension
If all goes well the skin package should be generated in the "Portals/_default" folder.
Combine a skin and a container in one DNN 5 package
Warning: do not try to pack a DNN 5 skin and a container the way you did in DNN 4 (Skins.zip and Containers.zip files, zipped together) , it will not install!
This is quite a simple task as you can combine multiple extensions in one package.
A. Convert both the skin and the container to a DNN package as described above.
B. Copy the converted skin package file.
C. Open both the copied skin package and the container package (the zip files)
C. Copy all the files but the manifest file for the container package, to the copied skin package.
D. Now open both the skin and containers manifest file in a text editor.
E. Select the … block from the containers manifest file and paste it in the copied skins manifest file, below the skins existing … block.
F. Save the copied skins manifest file
The new package you just created will install both the skin and the container in DNN 5.
The combined skin / container package will show up in the extensions list as a skin (the container in the skinpack will not be listed separately under containers)
They are both visible onder admin > skins, so you can use them as usual