-
Notifications
You must be signed in to change notification settings - Fork 14
Templates
The Repository Module uses a ‘template’ system that provides you with complete control over the formatting of the module’s output. Templates are different than ‘skins’ in one basic respect, skinning’s primary goal is to change the way that something ‘looks’, while a template’s primary goal is to change the layout of the content. There is certainly some overlap between the two concepts, but keep in mind that Repository templates should be used in conjunction with your site’s skin and containers to provide a consistent look and feel experience for your users. Because of this, there is no stylesheet ( .css ) file associated with a Repository template. Your templates are expected to use common class names so that they will blend in with your site’s look and feel.
Fig 1. A repository module with a template (metro) applied 
A Repository Template is made up of multiple sections, with each section controlled by a pair of files, one .HTML file with HTML markup and special Repository tokens, and an .XML file of the same name which allows you to specify any special settings for the tokens in your template.
The sections of a template are as follows:
- Header :: displayed once per page at the top of the module. Usually contains sorting options, category or attribute selection, searching capability and page navigation. If you want to insert some JavaScript or special stylesheet entries, this is where you would do that as well.
- Template :: the template.html and template.xml files are used to control the display of each item as it’s displayed in your module.
- Footer :: displayed once per page and the bottom of the module. Usually used for page navigation.
- Ratings Form :: this template file pair formats the User Rating form, when displayed.
- Comments Form :: this template file pair formats the User Comment form, when displayed to a user who can add/edit comments.
- View Comments Form :: this template file pair formats the display of User Comments when the current user cannot add/edit comments.
- Upload/Edit Form :: this template form is used for Uploading a new Repository item, or editing an existing item.
- Details :: this template provides a details page that takes up the entire module space and allows detailed information about the item to be displayed.
- Dashboards ( a pair for each Dashboard mode ).
As the Repository module prepares to render each item in your module, it uses the various template files to construct the overall module display. Regardless of the section, the rendering process is exactly the same. The .html file contains a combination of HTML tags and Repository tokens. HTML is passed through the parser “as-is”. Tokens are processed by the parser and replaced with data elements or UI elements.
Tokens are delimited by square brackets and the token name within the brackets tells the parser what to replace the token with when rendering the item. For example: when parsing a template, if a {"TITLE"} tag is encountered, the parsing engine will replace that token with the Item’s TITLE property. There are a large number of tokens that the parsing engine understands. Refer to the Token Reference for a list of tokens that are available for each template file.
Fig 2. A sample template with tokens
<TABLE CLASS="normal" WIDTH="100%" CELLSPACING="0" CELLPADDING="0">
<TR BGCOLOR="White">
<TD WIDTH="1" ALIGN="left" VALIGN="top">[EDIT]/TD>
<TD WIDTH="16" ALIGN="left" VALIGN="top" style="padding-right:2px;">[FILEICON]/TD>
<TD CLASS="normal" ALIGN="left" VALIGN="top">[TITLE]/TD>
<TD WIDTH="120" CLASS="normal" ALIGN="left" VALIGN="top">[UPDATEDDATE]</TD>
<TD WIDTH="30" CLASS="normal" ALIGN="left" VALIGN="top">[FILESIZE]/TD>
<TD WIDTH="80" CLASS="normal" ALIGN="left" VALIGN="top">[DOWNLOAD]</TD>
</TR>
</TABLE>
When the parsing engine replaces a token, it looks at the corresponding .XML file to see if there are any special Attributes specified for that particular token. Most tokens support the ability to assign a stylesheet class via a CssClass setting. In the following example from the default template.xml file, you see that the cssclass “SubHead” is being applied to the "[TITLE]" token. When the parsing engine renders the item’s TITLE, it will apply the “SubHead” class to it.
Fig 3. A sample settings (.xml) file
<Object>
<Token>[TITLE]/Token>
<Settings>
<Setting>
<Name>CssClass</Name>
<Value>SubHead</Value>
</Setting>
</Settings>
</Object>
Refer to the [Token Reference](Token-Reference) for a listing of Attributes that you can apply to each token.
There are two physical places where your template files may be stored. The default location is /DesktopModules/Repository/Templates. Each template’s collection of files will be stored in a folder. The folder name will be used as the name of the template. On your module’s Settings page, you’ll see a dropdown list of available templates. This list is populated with the names of the folders within the Templates folder. Select the template you want to apply to your module and update your settings. Templates are shared across all portals on your site.
Overriding a template for a single Portal You may also override a template’s behavior for a single Portal, by placing one or more template files in a folder of the same name in a /Portals/n/RepositoryTemplates folder.
For example: If you did not want to use Categories on your Repositories in Portal #2, but wanted all the other features of the default template, you would create a folder named /Portals/2/RepositoryTemplates/default and copy the header.html file, from the standard default template. Remove the "[CATEGORIES] token from the new header.html file, and you’re all done.
You do not have to copy the entire template from the /DesktopModules location, only the files that you wish to override from the shared template. All other files will be loaded from the shared location. This way you can have shared templates for use by all portals, and still have portal specific templates as well.
Currently, there is no built-in installation UI or process for templates. You must copy your template files via a manual process such as FTP to get the files in the proper place. In a future release, there will be a template admin feature where you can upload, edit, delete and otherwise manage your Repository templates.
One of the key features of the DotNetNuke core engine is the ability to “localize” your web site. In order to provide the ability to localize any static text in your templates, there are two special tokens that you can use, "[DNNLABEL:key]" and "[LABEL:key]".
When the parser processes one of these two tokens, it will load the text from a local resource file named Repository.ascx.resx which is located at /DesktopModules/Repository/App_LocalResources. The parse will look for a resource key named key.Text.
For example: If the token "[DNNLABEL:Intro]"} was found in a template, the text associated with the resource key Intro.Text would be rendered. The parser will look in the .xml setting file for "[Intro] token. Please note, that the DNNLABEL: is not included in the token name. The token name is actually “Intro”, the DNNLABEL: prefix just tells the parsing engine that it requires special handling.
The parser will replace a "[DNNLABEL:key]"} token with a DNN Label Control, which means that in addition to injecting the text from the resource file, it will also inject a small help icon and load the popup help text from the key.Help resource. In the previous example, the popup help text will be loaded from Intro.Help. The "[DNNLABEL:key]" token should be used for all input field prompts in your templates.
The "[LABEL:key]" token works exactly like the "[DNNLABEL:key]" token, except that it does not include a help icon or popup text. The "[LABEL:key]" should be used for static text elements in your templates.
All localization text is loaded from the Repository.ascx.resx file and shared by all templates, with the following exception, the Form template. Because the Form template is used to format the upload and edit input forms they can be used to tailor your Repository for drastically different purposes.
One template might be used for files that users will be able to download. Another template might be used as a photo gallery and only allow the uploading of images with no download capabilities. Because the purpose of uploading items to repositories can be so different, the Form template has its own resource file. Form resources are stored in the /DesktopModules/Repository/Templates/templatename/App_LocalResources in a file named Form.ascx.resx.
When parsing the Form.html template, the parser will look in the Form.ascx.resx file for the text associated with the resource keys for all "[DNNLABEL:key]" or "[LABEL:key]" tokens.