Skinning Add-Ons
Code Add-Ons
DotNetNuke provides mechanisms to extend the core portal functionality through the use of code add-ons. These add-ons can be packaged for easy distribution and installation. DotNetNuke supports three types of redistributable code packages: modules, skin objects, and providers. Although these are not the only mechanisms available for extending portal functionality, they are the only officially supported ones for distributing code add-ons.
Modules
A module, also known as a DotNetNuke Private Assembly (PA), represents a discrete set of application code that is used to extend the functionality of the DotNetNuke portal. A module provides a user interface for managing and displaying custom content in the portal. Unlike the other DotNetNuke code add-ons — skin objects and providers — modules are designed to be easily added to a page by the administrator. Each module can comprise one or more ASP.NET user controls and compiled assemblies. Like the main portal application, the module can take advantage of the Data Provider model to package providers for multiple database management systems. In addition to user controls and assemblies, a module can use other resources, including images, XML files, SQL scripts, text files, cascading style sheets, and resource archives.
Module Manifest File
Included in the module package is the module manifest file, an XML file that delineates the various elements that comprise a module package. The manifest file is organized to allow the portal to easily identify the module files and to determine the appropriate database entries necessary for the proper functioning of the module. Listing 17-1 shows the basic manifest file format. DotNetNuke recognizes two versions of DotNetNuke manifest files: version 2.0 and version 3.0. Each manifest file format recognizes different nodes, which directly correlate with various DotNetNuke features.
Listing 17-1: Module Manifest File Format
 |
<?xml version="1.0"encoding=" utf-8" ?> <dotnetnuke version="D.D" type="Module"> <folders> -- Contains one or more folder nodes <folder> <name /> <friendlyname /> -- V3.0* only <foldername /> -- V3.0* only <modulename /> -- V3.0* only <description /> <version /> <businesscontrollerclass /> -- V3.0 only <resourcefile /> <modules> -- Contains one or more module nodes <module> <friendlyname /> <cachetime /> -- V3.0* only <controls> -- Contains one or more control nodes <control> <key /> <title /> <src /> <iconfile /> <type /> <vieworder /> <helpurl /> -- V3.0 only <helpfile /> -- V2.0 only </control> </controls> </module> </modules> <files> -- Contains one or more file nodes <file> <path /> <name /> </file> </files> </folder> </folders> </dotnetnuke>
|
Let's take a few minutes to explore the individual XML nodes.
The root element is the dotnetnuke node. It contains two attributes, version and type:
<dotnetnuke version="D.D" type="Module">
The version attribute takes a numeric value. DotNetNuke supports two manifest file versions —"2.0" and "3.0". Version 1.0 modules are no longer supported.
The type attribute must be set to "Module" for both v2 and v3 formats but can contain additional values to distinguish between the different manifest file formats used by skin objects and providers. These two additional formats are discussed later in this chapter.
| Important | The v3 format has undergone some nonbreaking changes since it was first released. The additional supported elements are highlighted with an asterisk on the version number. |
The manifest provides a <folders> element for identifying a collection of individual module folders. A folder node represents a single DotNetNuke module. The folder node can contain 10 child elements as defined in Table 17-1.
| Element | Description | Required | Versions Supported |
|---|---|---|---|
| Name | Defines the default name of the module as well as the name of the directory that DotNetNuke will create in the DesktopModules folder if foldername is not set. | Yes | 2.0, 3.0 |
| friendlyname | Used to identify the module in the module drop-down list located on the Admin Control Panel that appears when a user is logged in as a Portal or Host Administrator. The Host Administrator can change the friendlyname at any time. This enables the administrator to present module names in a language other than English to his or her administrative users. | No | 3.0* |
| foldername | Defines the name of the folder where the module will be installed. This folder becomes the root from which all other module files are installed (.dll files are an exception to this rule because they must be installed to the application \bin directory). | No | 3.0* |
| modulename | Defines the name of the module that uniquely identifies it in the system. After a module is installed, the modulename cannot be changed. This name is only used internally to identify each distinct module type. | No | 3.0* |
| description | Used for creating the module description that is presented to the host when viewing modules on the Module Definitions page. | Yes | 2.0, 3.0 |
| version | The version of the module. This element must be in the format XX.XX.XX where X is a digit from 0 to 9. It is used to determine which dataprovider scripts to execute. During installation, any script that has a higher version number than the currently installed module version will be executed. If this is the first time the module has been installed, all script files will be executed. Scripts are executed in the order of their version numbers. | Yes | 2.0, 3.0 |
| businesscontrollerclass | Defines the qualified name of the primary business controller in the module. If the IPortable, ISearchable, or IUpgradeable interfaces are implemented by the module, they must be implemented in this class. This entry uses the format [namespace] .[class name], [assembly name]. Here's an example entry:
< businesscontrollerclass > DotNetNuke.Modules.Survey .SurveyController, DotNetNuke. Modules.Survey</ businesscontrollerclass>. | No | 3.0 |
| resourcefile | Identifies a zip file that is included in the module package. The resource file may contain any number of files, which will be installed using folder information defined in the resource file. Files placed in the resource file do not need to be delineated in the files collection of the manifest. | No | 2.0, 3.0 |
| modules | Defines a collection of modules that are installed in the current folder. These modules will be associated with the Desktop module defined by the current folder. See Table 17-2 for a description of each module element. | Yes | 2.0, 3.0 |
| files | Defines a collection of files that are installed in the current folder. See Table 17-4 for a description of each file element. | Yes | 2.0, 3.0 |
| Element | Description | Required | Versions Supported |
|---|---|---|---|
| friendlyname | Defines the name of the current module. This element is used primarily for display purposes to distinguish between multiple modules in a single Desktop module. | Yes | 2.0, 3.0 |
| cachetime | Currently unused. When activated in future versions, it will define the default cachetime value for the module when it is added to a page. | No | 3.0* |
| controls | Defines a collection of user controls that are installed as part of the current module. These controls may provide different user or administrative screens for this specific module. See Table 17-3 for a description of each control element. | Yes | 2.0, 3.0 |
| Element | Description | Required | Versions Supported |
|---|---|---|---|
| key | A unique identifier that distinguishes each control in a single module. The primary View control does not use the key element and must not be included in the control definition. The module can use these key values to determine the appropriate screen to display for the current module state. The portal will display this control on the Module Settings screen if the control key is set to Settings. | No | 2.0, 3.0 |
| title | Defines the text displayed in the module title bar for the module edit screen associated with the current control. The title is not used for the primary View control. | No | 2.0, 3.0 |
| src | The filename of the ASP.NET user control corresponding to the current control definition. The filename includes any path information relative to the current module folder. | Yes | 2.0, 3.0 |
| iconfile | Defines the icon file to display in the module title bar. The iconfile setting is ignored for the primary View control and a control with a key of Settings. | No | 2.0, 3.0 |
| type | Defines the security access level required to view the current control. This level is defined as a subset of the SecurityAccessLevel enumeration. Valid values include Anonymous, View, Edit, Admin, Host. | Yes | 2.0, 3.0 |
| vieworder | Orders the controls when they are injected into the admin UI when multiple controls are associated with the module using the same key. | No | 2.0, 3.0 |
| helpurl | Defines a URL for help information related to the current control. | No | 3.0 |
| helpfile | Defines a file for help information related to the current control. The file location is relative to the current module folder. This element was deprecated in 3.0 and has been replaced through the use of LocalResources. | No | 2.0 |
Additionally, the folder node contains two collection child elements, Modules and Files, which are described in Tables 17-2 and 17-4, respectively.
As shown in Listing 17-1, every module contains one or more controls that are described in the controls collection. Each control can contain the various elements described in Table 17-3.
| Element | Description | Required | Versions Supported |
|---|---|---|---|
| path | Defines a relative path to the module folder. The file defined by this node will be installed in this folder. | No | 2.0, 3.0 |
| name | The name of the file in the module package. If the file does not exist in the module package, an error is logged. | Yes | 2.0, 3.0 |
Listing 17-2 shows the manifest file for the Survey module. The Survey module is included with DotNetNuke as an example of how to build, package, and deploy modules. You can find the module package and source code in the /desktopmodules/survey directory of the standard DotNetNuke installation.
Listing 17-2: Sample Manifest for the Survey Module
|
<?xml version="1.0" encoding="utf-8" ?> <dotnetnuke version="3.0" type="Module"> <folders> <folder> <name>DNN_Survey</name> <friendlyname>Survey</friendlyname> <foldername>Survey</foldername> <modulename>DNN_Survey</modulename> <description> Survey allows you to create custom surveys to obtain public feedback </description> <version>03.01.00</version> <businesscontrollerclass> DotNetNuke.Modules.Survey.SurveyController, DotNetNuke.Modules.Survey </businesscontrollerclass> <resourcefile>SurveyResources.zip</resourcefile> <modules> <module> <friendlyname>DotNetNuke.Survey</friendlyname> <cachetime>0</cachetime> <controls> <control> <src>DesktopModules/Survey/Survey.ascx</src> <type>View</type> <helpurl>http://www.dotnetnuke.com/default.aspx?tabid=787</helpurl> </control> <control> <key>Edit</key> <title>Create Survey</title> <src>DesktopModules/Survey/EditSurvey.ascx</src> <iconfile>icon_survey_32px.gif</iconfile> <type>Edit</type> <helpurl>http://www.dotnetnuke.com/default.aspx?tabid=787</helpurl> </control> <control> <key>Settings</key> <title>Survey Settings</title> <src>DesktopModules/Survey/Settings.ascx</src> <iconfile>icon_survey_32px.gif</iconfile> <type>Edit</type> <helpurl>http://www.dotnetnuke.com/default.aspx?tabid=787</helpurl> </control> </controls> </module> </modules> <files> <file> <name>Survey.ascx</name> </file> <file> <name>EditSurvey.ascx</name> </file> <file> <name>Settings.ascx</name> </file> <file> <name>DotNetNuke.Modules.Survey.dll</name> </file> <file> <name>DotNetNuke.Modules.Survey.SqlDataProvider.dll</name> </file> <file> <name>03.01.00.SqlDataProvider</name> </file> <file> <name>Uninstall.SqlDataProvider</name> </file> </files> </folder> </folders> </dotnetnuke>
|
Packaging Modules
DotNetNuke private assemblies are packaged as zip files. Files included in the package are placed in predetermined directories as defined by the file type and manifest file settings. Any directory information contained in the zip file is ignored. Only files that are specifically delineated in the manifest file are extracted and saved to the portal directories. Figure 17-1 shows the survey module package that is included with DotNetNuke.
Figure 17-1
Special File Types
DotNetNuke recognizes four specific file types in the private assembly archive: DNN, DLL, ASCX, and dataprovider script. Although other file types may be included in the package, DotNetNuke treats these four types as special cases. The following list looks at each of these types and how they are handled during installation:
-
DNN: The .dnn file is the manifest file for the Module package. Each package must include a single manifest file that follows the format previously discussed. The manifest file can use any name, but it must have the .dnn extension. The manifest fully describes each file included in the package and identifies information needed by the portal to create the proper module definition entries and install the module files to the appropriate directories required by DotNetNuke. The .dnn file is copied to the module folder defined in the manifest.
-
DLL: .dll files are .NET assemblies. In DotNetNuke, these assemblies can represent the compiled module code, a dataprovider assembly, or even an ASP.NET Server Control used in the module. All DLL files are installed to the application directory (/bin).
-
ASCX: .ascx files are the visual portion of a user control in ASP.NET. An .ascx file defines the layout of the user interface for the specific module. It is copied to the module folder and a special entry is made in the DotNetNuke system tables as specified in the manifest file. The ASCX file can represent a single module control or can be a constituent control that is used on multiple screens within the module. All module controls are defined in the manifest, whereas constituent controls appear only in the manifest file list.
-
Dataprovider script: Dataprovider files contain SQL scripts that define the database-specific code for the module. This file type uses an extension that follows a standard pattern: .[DataProvider Type]DataProvider, where [DataProviderType] corresponds to the provider type defined in the DotNetNuke web.config file (Access, Sql, Mysql, Oracle, Firebird and so on). For example, the default dataprovider supports SQL Server and is designated with the .sqldataprovider extension. New dataproviders may be written by third-party vendors, in which case new dataprovider script file types will be defined by the vendor. Dataprovider scripts are installed to a subdirectory of the Providers/DataProviders folder. The subdirectory is created with the same name as the dataprovider type (for example, SQLDataProvider files are installed in the providers/ dataproviders/sqldataprovider directory).
| Important | DotNetNuke 4.0 only includes a dataprovider for Microsoft SQL Server. Additional dataproviders will be provided as part of a separate DotNetNuke-sponsored project. Data providers for Oracle and MySQL are also available from third-party vendors. |
Resource File
In addition to the predefined file types, the module package also allows for the inclusion of a resource file. A resource file is a zip file that can contain any file that is not one of the special types defined earlier. As indicated previously in Table 17-1, the resource file is designated with the <resourcefile> node of the manifest file. Unlike the main module zip file, all directory information in the resource file is used to determine the appropriate directory in which to place the individual resources. Any directory that is defined will be created relative to the main module directory as defined in the manifest. Files that are placed in the resource file should not be delineated in the manifest file; however, the resource file must be specified in the manifest. Figure 17-2 shows the contents of the SurveyResources.zip file defined in the survey module manifest previously presented in Listing 17-2.
Figure 17-2
Notice that the *.resx files included in the resource file include path information. These files must be installed in the [module folder]/App_LocalResources directory to function correctly. DotNetNuke will place these files in the folder you designate (relative to the module folder), so you need to make sure to include the correct folder when building your resource file.
Installing Modules
After you have created a manifest file and properly packaged your module, it is ready for installation. The use of the zip file format and a well-defined manifest format greatly simplifies module installations. Because of the potential security risk, only the Portal Host has permissions to install modules. DotNetNuke supports two distinct methods for installing modules as well as other add-ons: web-based file upload and FTP-based file upload. These two methods differ primarily in the mechanism used for transferring the file to the server. After DotNetNuke receives the file, all processing is the same.
Web-Based File Upload
Follow these four simple steps to install a new module into your portal using the web-based installer.
-
Log in with the Host account and go to the Module Definitions page from the Host menu (see Figure 17-3). Only the Host account is authorized to install modules because modules have full access to the portal including file and database access.
Important Modules can pose a security risk because they have unlimited access to the portal. Module code has the same security privileges as the core application. This means that modules could alter key portal tables, manipulate application files, or even gain access to other server resources. Modules should be fully tested in a "safe" environment prior to installation in a production system. In addition, the portal should run in a partial trust environment, which would limit the capability of any module to access restricted resources.
-
On the Module Definitions page, select the Upload New Module menu item from the module action menu (see Figure 17-4).
-
The File Upload screen provides a simple interface for uploading one or more modules (see Figure 17-5), and different add-on types. Browse to the desired module 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.
-
After installing a new module, review the upload logs (see Figure 17-6). Errors will be highlighted in red. If no errors are shown, the module is ready for use in your portal.
Figure 17-3
Figure 17-4
Figure 17-5
Figure 17-6
FTP-Based Installation
DotNetNuke includes support for file-based installation of all defined add-on types. The framework includes a scheduled task that runs every minute to check installation folders for new add-ons to install. If you do not need this service, you can disable the scheduled task from the Schedule page in the Host menu.
To install a new module using FTP or any file manager, copy the module into the Install/Module directory of your DotNetNuke installation. When the ResourceInstaller task runs, it will install the module using the standard module installation code. If an error occurs, it will be noted in the task history, which you can access by selecting the History link for the ResourceInstaller task on the Schedule page (see Figure 17-7).
Figure 17-7
Skin Objects
Skins objects, like modules, are active elements designed to programmatically extend the functionality of DotNetNuke. Skin objects are used in skins and containers to produce a dynamic user interface. A number of default skin objects are included with DotNetNuke for common portal functions such as login, status, and navigation, as described in Table 17-5.
| HTML Token | ASCX Control | Usage | Description |
|---|---|---|---|
| [ACTIONBUTTON] | < dnn: ActionButton runat=>"server" id= "dnnActionButton" command name. | Container | Displays a list of link buttons that correspond to action menu items with a specified |
| [ICON] | < dnn:Icon runat= "server" id=> "dnnIcon" | Container | Displays an icon for the module. If the icon module was not set on the Module Settings page, no icon is displayed. |
| [PRINTMODULE] | < dnn: PrintModule runat="server" id= "dnnPrintModule"> | Container | Displays an image button for printing module contents. |
| [ACTIONS] | < dnn: Actions runat= "server" id= "dnnActions"> | Container | Displays the module action menu using the Solpart Menu control. |
| [SOLPARTACTIONS] | < dnn:SolpartActions runat="server" id= "dnnSolpartActions"> | Container | Displays the module action menu using the Solpart Menu control. This is the same as the [ACTIONS] skin object. |
| [DROPDOWNACTIONS] | < dnn: DropDownActions runat="server" id= "dnnDropDownActions"> | Container | Displays the module action menu items using a drop-down list. |
| [LINKACTIONS] | < dnn: LinkActions runat=>"server" id= "dnnLinkActions" | Container | Displays the module action menu items using a series of link buttons. |
| [TITLE] | < dnn:Title runat= "server" > | Container | Displays the module title. |
| [VISIBILITY] | < dnn:Visibility runat=>"server" id= "dnnVisibility" | Container | Displays the expand/collapse button for hiding or displaying module contents. |
| [SIGNIN] | < dnn:Signin runat= "server" id= "dnnSignin"> | Skin | Displays the sign-in control for providing your username and password. |
| [BANNER] | < dnn:Banner runat= "server" id= "dnnBanner"> | Skin | Displays a random banner ad. |
| [BREADCRUMB] | < dnn:Breadcrumb runat="server" id= "dnnBreadcrumb"> | Skin | Displays the path to the currently selected page in the form of PageName1 > PageName2 > PageName3. |
| [CONTENTPANE] | <div runat="server" > | Skin | A placeholder for content modules. |
| [COPYRIGHT] | < dnn:Copyright runat= "server" id= "dnnCopyright"> | Skin | Displays the copyright notice for the portal. |
| [CURRENTDATE] | < dnn:CurrentDate runat="server" id= "dnnCurrentDate"> | Skin | Displays the current date. |
| [DOTNETNUKE] | < dnn:DotNetNuke runat="server" id= "dnnDotNetNuke"> | Skin | Displays the copyright notice for DotNetNuke. |
| [HELP] | < dnn:Help runat= "server" > | Skin | Displays a link for Help that will launch the user's e-mail client and send mail to the portal administrator. |
| [HOSTNAME] | < dnn:HostName runat= "server" id= "dnnHostName"> | Skin | Displays the Host Title linked to the Host URL. |
| [LANGUAGE] | < dnn:Links runat= "server" id= "dnnLanguage"> | Skin | Displays a language selector drop-down list that allows the user to select the localized version of the site to display. This overrides the user's default language setting. This skin object is displayed only if a second language is installed for the portal. |
| [LINKS] | < dnn:Links runat= "server" > | Skin | Displays a flat menu of links related to the current tab level and parent node. This is useful for search engine spiders and robots. |
| [LOGIN] | < dnn:Login runat= "server" > | Skin | Dual-state control. Displays "Login" for anonymous users and "Logout" for authenticated users. |
| [LOGO] | < dnn:Logo runat= "server" > | Skin | Displays the portal logo. |
| [PRIVACY] | < dnn:Privacy runat=" server" id= "dnnPrivacy"> | Skin | Displays a link to the privacy information for the portal. |
| [SEARCH] | < dnn:Search runat= "server" id= "dnnSearch"> | Skin | Displays a search input box and link button. |
| [MENU] | < dnn:Menu runat= "server" id=>"dnnMenu" | Skin | Displays the hierarchical navigation menu. |
| [SOLPARTMENU] | < dnn:SolpartMenu runat="server" id= "dnnSolpartMenu"> | Skin | Displays the hierarchical navigation menu. This is the same as the [MENU] skin object. |
| [TERMS] | < dnn:Terms runat= "server" > | Skin | Displays a link to the terms and conditions for the portal. |
| [TREEVIEW] | < dnn:TreeView runat=> "server" id= "dnnTreeView" | Skin | Displays a tree-based menu of links for the portal pages. The menu can be set to limit the tree to various menu levels. |
| [USER] | < dnn:User runat= "server" id=>"dnnUser" | Skin | Dual-state control. Displays a "Register" link for anonymous users or the user's name for authenticated users. |
Custom skin objects are packaged and installed using the same processes as custom modules. All of the necessary skin object resource files are combined with a DotNetNuke manifest file (*.dnn) and packaged into a compressed zip file. Follow the installation steps outlined in the "Installing Modules" section earlier in the chapter. The primary difference between modules and skin objects is the manifest file format.
The skin object manifest file format (see Listing 17-3) is derived from version 2 of the module manifest format (shown previously in Listing 17-1). Changes are highlighted.
Listing 17-3: Skin Object Manifest File Format
|
<?xml version="1.0" encoding="utf-8" ?> <dotnetnuke version="D.D" type="SkinObject"> -- Changed type value <folders> <folder> <name /> <description /> -- Not used <version /> -- Not used <resourcefile /> <modules> <module> <friendlyname /> -- Not used <controls> <control> <key /> <title /> <src /> <iconfile /> <type /> -- Changed valid values <vieworder /> </control> </controls> </module> </modules> <files> <file> <path /> <name /> </file> </files> </folder> </folders> </dotnetnuke>
|
The type attribute of the root dotnetnuke node must be set to "SkinObject". Unlike modules, skin objects ignore the version value. The version must still be a decimal number in the format D.D where D is a single digit.
| Important | Although there is no restriction on the actual number, it should be set to 2.0 to prevent conflicts with future versions of the skin object format. |
The description, version, and friendlyname elements are no longer used but are still allowed in the manifest file without causing a validation error. The type element must be set to "SkinObject". The name element will be used to set the friendlyname, foldername, and modulename attributes for the skin object in the database.
Providers
Providers are a third mechanism for extending the functionality of the DotNetNuke portal framework. The primary difference between modules, skin objects, and providers is in the usage pattern. Modules provide a mechanism for extending system functionality. No two modules are guaranteed to provide the same functionality or implementation. Skin objects follow this behavior, with each skin object being free to implement whatever functionality is desired. Providers are unique in that each provider of a given type must implement the same functionality. The implementation details may change but the basic functionality (that is, the programming interface) is defined by the portal.
Because providers are a programmatic extension to the portal framework, they use the packaging and installation mechanism defined for modules. Like skin objects, providers have their own manifest file format (see Listing 17-4), which is derived from the module manifest format.
Listing 17-4: Provider Manifest File Format
|
<?xml version="1.0"encoding="utf-8" ?> <dotnetnuke version="D.D" type="Provider"> -- Changed type value <folder> <name /> <type /> <files> <file> <path /> <name /> </file> </files> </folder> </dotnetnuke>
|
The type attribute of the root dotnetnuke node must be set to "Provider". Providers follow the same rules as skin objects for the version attribute. Tables 17-6 and 17-7 describe the manifest folder and file elements.
| Element | Description | Required |
|---|---|---|
| Name | Defines the name of the provider. This name is used to create the folder in the appropriate provider directory. | Yes |
| Type | The provider type. It can be either DataProviders or LoggingProviders. Yes Additional provider types will be supported in future releases. | Yes |
| Files | Defines a collection of files that are installed in the current folder. See Table 17-7 for a description of each file element. | Yes |
| Element | Description | Required |
|---|---|---|
| Path | Defines a relative path to the provider folder. | No |
| Name | The name of the file in the provider package. If the file does not exist in the provider package, an error will be logged. | Yes |
Files in the provider package are installed as follows:
[DotNetNuke Root Folder]/Providers/[ProviderType]/[FolderName]/[FilePath]/[FileName]
EAN: 2147483647
Pages: 182
- Chapter III Two Models of Online Patronage: Why Do Consumers Shop on the Internet?
- Chapter IV How Consumers Think About Interactive Aspects of Web Advertising
- Chapter VIII Personalization Systems and Their Deployment as Web Site Interface Design Decisions
- Chapter XVII Internet Markets and E-Loyalty
- Chapter XVIII Web Systems Design, Litigation, and Online Consumer Behavior