Language Add-Ons


Skinning Add-Ons

Whereas code add-ons are designed to extend the functionality of the portal, skinning add-ons are aimed at giving the portal administrator complete control over the visual appearance of the portal. To simplify development and maintenance of these skinning packages, no manifest files are required. Instead, skinning packages rely on zip files to package and group the files to be installed in support of a skin. Although they do not utilize manifest files, skinning packages include support for XML-based configuration files. Configuration files enable the designer to set properties on individual skin elements that are identified inside the skinning source files. These skin elements include all skin objects as well as content panes defined within the skin definition file.

DotNetNuke uses two mechanisms for grouping content in the portal: pages and modules. Skins provide a method for changing the appearance of individual pages, whereas containers provide this function for each module instance placed on a page. First take a look at how skins are packaged and deployed.

Skins

As discussed in Chapter 16, skins provide the primary method for controlling the appearance of individual portal pages. One of the primary goals for the DotNetNuke skinning solution was to create a simple the process for developing and packaging skins. This process should allow web designers as well as developers to create skins using a variety of tools, from simple HTML editors to complex IDEs like Visual Studio .NET. This separation of form and function is one of the strengths of the DotNetNuke skinning solution.

Packaging Skins

A skin package comprises multiple files that constitute a complete skin:

  • .htm, .html files: Abstract skin definition files that will be processed by the Skin Uploader to create an .ascx file.

  • .ascx files: Skin-definition user controls that are written in the format required by the skin engine.

  • .css files: Styles sheets that are related to skins.

  • .gif, .jpg, .jpeg, .png files: Support graphics files.

  • .xml files: Abstract skin properties files that will be combined with the abstract skin definition files during the upload processing.

  • .zip files: Skin and container packages that are named according to the parent package.

Important 

You can include any additional files needed by the skin, but they must be one of the allowable file types defined in the Host File Upload Extensions setting.

A skin package can contain multiple skin files. This enables you to create skins that leverage the same graphics but vary slightly based on layout. Obviously, the more skin files you have in a package, the more maintenance is required when you want to make a general change to the presentation in the future. When you're packaging files for the skin, zip the files using relative file paths to the skin definition files. When unpacked, all file paths in the definition file will be corrected to point at the new file locations in the portal. Files are unzipped using the file path information contained in the skin package.

Important 

Make sure that relative file path information in the zip file matches the relative path information in the skin definition files.

The following example shows two different graphic images from an abstract skin definition file:

 <IMG src="/books/3/435/1/html/2/top_left.gif" height="10" width="10" border="0"> <IMG src="/books/3/435/1/html/2/images/top_right.gif" height="10" width="10" border="0"> 

The files should be included in the package as shown in Figure 17-8.

image from book
Figure 17-8

If the preceding code snippet was contained in a package called MySkin.zip, the resulting image tags after installation would look this:

 <IMG src="/books/3/435/1/html/2//Portals/_default/Skins/MySkin/top_left.gif" height="10" width="10" border="0"> <IMG src="/books/3/435/1/html/2//Portals/_default/Skins/MySkin/images/top_right.gif" height="10" width="10" border="0"> 

Skin packages can contain files that are applied to all skin definition files in the package or that are specific to an individual skin definition as outlined in Table 17-8. Any properties or styles set in the global file (if present) are overwritten with the value from the corresponding file that is specific to an individual skin. Graphics and any additional files stored in the skin package are global in scope and may be referenced by any skin definition file included in the package.

Table 17-8: Skin Filenames

File Type

Global Name

Individual Skin Name

Configuration file

Skin.xml

[skin filename].xml

Style sheet

Skin.css

[skin filename].css

In many cases, you will want to package a complementary set of skin files and container files in one distribution file. To do so, you need to package your container files in a zip file named containers.zip. Similarly, you must package your skin files in a zip file named skins.zip. Then you need to package these two files into a single zip file that is named after your skin. This enables people to install the full skin package (skins and containers) by uploading a single file through the Skin Uploader.

DotNetNuke contains a Skin Gallery for previewing skins installed in the portal. For the skin to be viewable in the Skin Gallery, you need to create a high-quality screenshot of your skin. For each skin or container definition file (both HTML-and ASCX-based definitions) you should also have a corresponding screenshot stored with a .jpg file extension (that is, if your skin file is named myskin.html, your screenshot needs to be named myskin.jpg).

If the skin package contains an about.htm file, the Skin Gallery will include an About <skin name> button below the gallery images. Clicking that button opens the designer-supplied about.htm file.

Skin Configuration Files

When creating abstract skin definition files (HTM or HTML files), the designer places tokens in the skin to designate locations for skin objects or content panes. To control the behavior and appearance of the skin objects and panes, the author may optionally choose to include one or more configuration files in the skin package. Any public property or field of a skin object or content pane can be set using the configuration file. As noted earlier, the global Skin.xml file property settings are applied to all skins. If present, these property settings may be overridden by a skin-specific configuration file as well.

The skin configuration file uses a simple format, as shown in Listing 17-5.

Listing 17-5: Skin Configuration File Format

image from book
 <Objects>   <Object>     <Token />     <Settings>       <Setting>         <Name />         <Value />       </Setting>     </Settings>   </Object> </Objects> 
image from book

Table 17-9 describes the relevant elements from the skin configuration file.

Table 17-9: Configuration File Elements
Open table as spreadsheet

Element

Description

Objects

Contains one or more Object nodes that provide property settings for the individual skin element.

Token

Defines the skin element to update with the associated settings. This value must match a token that exists in the associated skin definition files.

Settings

Contains one or more Setting nodes that provide the individual name/value pairs for a single skin element property.

Name

The name of the skin object property or attribute. If the skin object does not support this attribute, an error may be thrown when the skin is used in the portal.

Value

The value to assign to the skin object attribute. If this is an invalid value, an error may be thrown when the skin is used.

The skin configuration file format enables the author to easily set one or more attributes for each token included in the skin. As you know, each skin object has its own set of supported attributes. The Skin Uploader merges the skin attributes with the HTML presentation file to create an ASCX skin file.

Important 

If you are creating ASCX skins, you need to specify the attribute directly in your skin file (that is, <dnn:Login runat="server" Text="Signin" />), and no configuration file is necessary.

Please note there is a one-to-one correspondence of skin object declarations in your skin file with the attribute specification in the XML file. This is also true for named instances. For example, if you want to include a vertical and horizontal set of navigation links in your skin, you can specify [LINKS:Vertical] and [LINKS:Horizontal] named instances in your skin file and then create definitions for each with different attributes in your XML file.

Listing 17-6 shows a sample configuration file that is used in the PHPDupe skin.

Listing 17-6: Skins Configuration File Format

image from book
 <Objects>   <Object>     <Token>[LINKS:Horizontal]</Token>     <Settings>       <Setting>         <Name>Separator</Name>         <Value><![CDATA[&nbsp;&nbsp;|&nbsp;&nbsp;]]></Value>       </Setting>       <Setting>         <Name>Level</Name>         <Value>Root</Value>       </Setting>     </Settings>   </Object>   <Object>     <Token>[LINKS:Vertical]</Token>     <Settings>       <Setting>         <Name>Level</Name>         <Value>Child</Value>       </Setting>       <Setting>         <Name>Alignment</Name>         <Value>Vertical</Value>       </Setting>       <Setting>         <Name>Separator</Name>         <Value><![CDATA[<b><big>&nbsp;&middot;&nbsp;&nbsp;</big></b>]]></Value>       </Setting>     </Settings>   </Object>   <Object>     <Token>[DOTNETNUKE]</Token>     <Settings>       <Setting>         <Name>CssClass</Name>         <Value>Copyright</Value>       </Setting>     </Settings>   </Object> </Objects> 
image from book

When settings are applied to the abstract skin file, they are injected in the control tag as attributes and take the form Name="Value". So based on the skin objects previously defined in Table 17-5, when the preceding configuration file is used, the [DOTNETNUKE] token will be replaced with the following control reference:

 < dnn:DotNetNuke runat="server" Css> 

Installing Skins

Unlike code add-ons, skins can be installed by portal administrators as well as by hosts. Skins also support web-based file upload or FTP based-file upload.

Web-Based File Upload

Use the following four steps to install a new skin into your portal using the web-based installer. Where the skin files are saved and which portals in a multi-portal site will have access to the skin depend on whether you install the skin from the Admin or the Host menu.

  1. Log in with an Admin or Host account. If you are installing a skin for the current portal, go to the Admin/Site Settings menu (see Figure 17-9). Skin files will be stored in the individual portal directory. If multiple portals upload the same skin, duplicate files will exist in the portal directories.

    If you want all of the portals in a multi-portal installation to have access to the skin, log in with the Host account and select the Host/Host Settings menu (see Figure 17-10).

  2. Figures 17-11 and 17-12 show the key portions of the Portal Settings and Host Settings screens. Select the Upload Skin link to go the File Upload screen.

  3. The File Upload screen provides a simple interface for uploading one or more skins (see Figure 17-13). Browse to the desired skin package, click OK on the Browse dialog, and click the Add link on the File Upload page. Use the Upload New File link button to finish installing the module.

  4. After installing a new skin package, review the upload logs (see Figure 17-14). Errors are highlighted in red. If no errors are shown, the skin is ready for use in your portal. The location of the installation directory is displayed at the top of the logs. Note that the directory matches the name of the skin package and will only vary based on whether the skin is installed from the Admin menu or the Host menu.

image from book
Figure 17-9

image from book
Figure 17-10

image from book
Figure 17-11

image from book
Figure 17-12

image from book
Figure 17-13

image from book
Figure 17-14

FTP-Based Installation

To install a new skin using FTP or any file manager, copy the module into the Install/Skin directory of your DotNetNuke installation. When the ResourceInstaller task runs, it will install the skin using the standard skin installation code. Any errors that occur will be noted in the task history, which is available by selecting the History link for the ResourceInstaller task on the Schedule page (shown previously in Figure 17-7).

Containers

Containers, like skins, provide the ability to control the appearance of portal. Whereas skins work at the "page" level, containers are designed for wrapping individual modules that appear on the page. Each module on a given page can use any one of the installed containers. Containers follow many of the same packaging and installation processes as skins and differ primarily in the allowable content inside the HTML or ASCX definition files. The following sections provide a look at these differences.

Packaging Containers

Containers follow the same packaging rules as skins. Container packages can contain files that are applied to all container definition files in the package or that are specific to an individual container definition as outlined in Table 17-10. The behavior and purpose of these files is the same as for skins; only the names of the files are different.

Table 17-10: Container Filenames

File Type

Global Name

Individual Container Name

Configuration file

Container.xml

[container filename].xml

Style sheet

Container.css

[container filename].css

Installing Containers

Containers follow the same procedures for web-and FTP-based installations. For web-based installations, in step 2, select the Upload Container link instead of the skin link (shown previously in Figures 17-11 and 17-12). Containers will be installed in the Portal or Host containers directory. To install containers using FTP, place the container package in the Install/Container directory.




Professional DotNetNuke 4.0 (c) Open Source Web Application Framework for ASP. NET 4.0
Professional DotNetNuke 4: Open Source Web Application Framework for ASP.NET 2.0 (Programmer to Programmer)
ISBN: 0471788163
EAN: 2147483647
Year: 2006
Pages: 182

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net