New to Version 3.0
XMod has a new feature that enables you to more easily share form and template code. Additionally it allows you to install plug-ins and custom controls. You do this by creating "packages". Each package is simply a ZIP file that contains an XMod installation script, and one or more form files, template files, plugins, and custom controls.
For the most part all you need to know is how to install a package. Simply go to the Administration page - available to admins and hosts via the Actions menu.
PROBLEMS?: Your site's host may have disabled the uploading of XMod packages. In that case, you'll be presented with a message noting that fact. You won't be able to upload packages. Some hosts may allow the uploading of packages but may selectively disallow certain types of files (like plug-ins and custom controls). Additionally, the package installation process may not operate correctly on some sites that run in Medium Trust. In those cases, you can still just unzip the package file and use the contents of each *.xmf file to create new forms and use the contents of each new *.xmt file to create new templates. If the package contains any DLL files or SQL scripts, you'll need to have the Host install those by uploading the DLL's to the \bin directory of your DNN installation and execute any SQL scripts.
To install a package, browse to the file on your local drive by clicking the "Browse" button in the "Install Package" section of the page. Then click the "Install" link. After the file has been installed, you'll be presented with a log describing the success and/or failures encountered during installation.
Packages are ZIP files that must contain an XMod Installation script. Similar to DotNetNuke's ".dnn" script, this is an XML file saved with an .xmi extension. It looks similar to this:
<?xml version="1.0" encoding="utf-8"?>
<xmod version="1.0">
<folder>MyBlueHeaven</folder>
<files>
<file>
<title>My Blue Heaven ListView</title>
<name>MyBlueHeaven_List.xmt</name>
<description>This is the list view template for My Blue Heaven</description>
<type>listview</type>
</file>
<file>
<title>My Blue Heaven DetailView</title>
<name>MyBlueHeaven_Detail.xmt</name>
<description>This is the detail view template for My Blue Heaven</description>
<type>detailview</type>
<key>MyBlueHeaven.DetailView</key>
</file>
<file>
<title>My Blue Heaven Data-Entry Form</title>
<name>MyBlueHeaven_Form.xmf</name>
<description>This is the data-entry form for My Blue Heaven</description>
<type>form</type>
<key>MyBlueHeaven.MainForm</key>
</file>
<file>
<title>My Blue Heaven Display Plugin</title>
<name>MyBlueHeaven.dll</name>
<description>This is a plugin that does MyBlueHeaven Stuff to the Display</description>
<type>plugin</type>
</file>
<file>
<title>My Blue Heaven Custom Control</title>
<name>MyBlueHeavenCtrls.dll</name>
<description>This is a custom control that does MyBlueHeaven Stuff in a form</description>
<type>customcontrol</type>
</file>
<file>
<title>My Blue Heaven SQL Script</title>
<name>MyBlueHeavenCtrls.sql</name>
<description>This is a SQL Script file for MyBlueHeaven package</description>
<type>other</type>
</file>
</files>
<system>
<plugins>
<plugin>
<title>My Blue Heaven System Plugin</title>
<assembly>MyBlueHeaven.dll</assembly>
<classname>MyBlueHeaven.XModPlugins.SysPluginClass</classname>
</plugin>
</plugins>
</system>
</xmod>
There are 5 main file types recognized by XMod:
XMod Template Files (*.xmt): These are template definition files and can be either detailview or listview templates, as specified by the <type> tag. The contents of these files are the same as what you'd enter via the Manage Templates page. During installation, the special placeholder {XMOD_InstallDir} will be replaced by the directory into which supporting files are installed. This allows templates to reference images and other supporting files.
XMod Form Files (*.xmf): These are form definition files - the contents of which are the same as what you'd enter via the Manage Forms page. During installation, the special placeholder {XMOD_InstallDir} will be replaced by the directory into which supporting files are installed. This allows forms to reference images and other supporting files.
XMod Installation Scripts (*.xmi): This is described above.
Custom Controls and Plug-Ins (*.dll): These are program files created by developers to extend the functionality of XMod.
SQL Scripts (*.sql): These are files that contain SQL scripts to be executed during package installation. During installation, standard DNN placeholders like {databaseOwner} and {objectQualifier} will be processed.
Other Files: At the host's discretion, XMod can be made to allow other file types. These files will typically be supporting files such as images, "middle-tier" script files like ASP pages, style sheets, etc.
To create a package, zip one or more of the file types outlined above, together with a properly formatted .xmi file. The entries in the .xmi file must match the contents of the ZIP file. There can be only one .xmi file in a package.
XMI files are XML files that have a root node of <xmod> This tag must contain the ' version="1.0" ' attribute so that XMod can distinguish between future file formats.
The <xmod> tag must contain one <folder> tag. This specifies the folder into which supporting files will be placed. During installation, if supporting files are found, XMod will look in the portal's upload directory, under the "xmod/packages" sub-directory, for the folder name. If it's not found, XMod will attempt to create the directory and it will copy the supporting files to that folder.
Within the <xmod> root node is the <files> tag, which serves as a container for <file> tags. You should have one <file> tag for each file in the zip file.
Each <file> tag describes a single file in the package through the use of up to five child tags:
<title> This is the name XMod should use when displaying the file to the user. For template and form files, this will become the name of the item when it is installed in the database.
<name> This is the name of the file.
<description> This is a short description of the file.
<type> This tells XMod what kind of file it is. These are the valid values:
listview : A List View template
detailview : A Detail View template
form : A form definition.
plugin : A file containing one or more display plugins.
customcontrol : A file containing one or more custom controls to be used in an XMod form.
other : A supporting file for the package, such as an image, an ASP file, SQL Script file, style sheet, etc.
<key> This optional tag is used only for Forms and Templates. It is used by package developers to link a form or template to a unique key. This key is used during package installation and during subsequent upgrades. During installation, XMod will look for forms/templates with that key and update them with the new form/template. If no form/template is found, XMod will create a new record for the form/template.
For more information on System Plugins, see System Plugins Overview
Within the <xmod> root node is the <system> tag, which serves as a container for <plugins> tag, which, in turn, is the container for <plugin> tags. You should have one <plugin> tag for each system plugin you wish to register for the current portal. NOTE: If the DLL that contains your plugin is already installed on the web server, you don't need to include it in the ZIP file, just create a registration for it via the <plugin> tag.
Each <plugin> tag describes a single assembly and class within that assembly that implements the ISystemPlugin interface (found in the KnowBetter.XMod.Extensibility.Plugins namespace). The tag has 3 child tags which contain information XMod uses at run-time to invoke your class.
<title> This is a friendly name for the plugin. Its primary use is to aid the user in identifying what the plugin does.
<assembly> This is the name of the DLL file that contains the plugin. You should specify the file's name, without any path information and without the ".dll" extension.
<classname> This is the name of the plugin class. XMod will attempt to load this class from the assembly, convert it to the ISystemPlugin interface, and call the appropriate methods. This should be a fully qualified name, including the namespace for the class.