Templated View

Templated View

This document outlines how to modify and make your own templates for use in Document Exchange. Template View is invoked by selecting TemplateView as the control to load for the module (see below).

Templates location

The module comes with a number of preconfigured templates that we hope are a good starting point for learning how to tune the templates to your own layout. The original templates are stored in DesktopModules/Bring2mind/DMX/Resources/ViewTemplates. If you edit these they will first need to be copied to your portal’s template directory: Portals/[PortalId]/DMX/ViewTemplates. You can get to the editor through the “Edit Templates” link at the bottom of the screen:

Note that the template files are plain text files and you can edit them equally well with a text editor on the server. The template files are stored in folders which take the name of the template.

Managing and Editing Templates

If you click on Edit Templates you’ll go to the template management screen:

Select Template

This lists all available templates. This includes the so-called “System” templates that came with DMX as well as the site’s own “Local” templates.

Download

Note you can download the selected template. This will zip up all the files and allow you to edit them somewhere else or upload them to another DMX.

Copy Template

Use this to copy a template. Since system templates are not editable you can use this to create a local copy which you can subsequently edit. Enter a name in the textbox for the new template.

Upload

You can transfer templates by downloading and uploading. They are transferred as zip files. Don’t forget to give the template a name in the textbox.

Editing

Once you’ve created your own local copy you can edit the template through the edit button just underneath:

This opens up an edit window and allows you to edit the html files online. Note that this mechanism is really meant to provide easy and quick access to the template in case you really need to something quickly. We suggest that while designing the templates you use a local site and use a text editor to just edit the templates directly which is probably much faster.

Templating Mechanism

The engine is designed to be driven through the querystring. This means the page will reload every time the user clicks something and the parameters in the querystring tell DMX what content to use to render the templates. The most basic querystring parameter in the module is EntryId. This is an integer value that points to a particular entry in DMX. It is unique and is therefore the best way to access data in DMX. If the querystring contains EntryId then the templating engine assumes this is the requested entry and will respond accordingly. Note you can also access the child entries (folder contents) based on this parameter. An alternative is CategoryId. As you’ll probably guess this access data in DMX based on category.

Templates are basically HTML files that include tokens (using a square bracket ‘[token]’ notation) that refer to the content to display. The DMX templating engine is a variation of the DotNetNuke core templating engine (called “Token Replace”).

Regular Token Formatting

A token normally takes the form of

[object:property|format]

The format is used to format the returned value from the property to render on screen. This follows regular DNN usage. There is one extension to this. If the property is a Boolean, the format is expected to be a pair of values separated by semicolon that lists the true-false return value. So

[button:new_visible|block;none]

will return ‘block’ or ‘none’ depending on the current user’s ability to see the new button. Other formatting still works as for instance

[entry:LastModified|g]

will display the Last Modified date of the entry in general date format of the current locale.

Template structure

A template is basically a collection of html/css/js files in a single directory. The main template is the Template.html file. This is the one that gets loaded first and is the “entrypoint” for the engine. All other html files are what’s known as subtemplates. If applicable, sub templates will be loaded and added to the content.

Subtemplates

As mentioned above the DMX templating engine is an extension of the DNN core token replace engine. The revisions we made allow the templating engine to do two things that are impossible to do in DNN’s engine (up to this point in time anyway): repetition and conditionals. Repetition means repeating a subtemplate over a number of iterations and conditionals refers to the ability to optionally load in a subtemplate based on a condition. For this we needed to devise our own syntax which we’ll explain below. The syntax remains within the basic square bracket syntax for token replace that is so familiar for token replace.

Repeating Templates

Repetition is achieved by a token that takes the following form:

[subtemplate|template filename|collection to repeat|parameters]

“subtemplate” is the marker to signal processing of a subtemplate.

Template Filename

Template filename is the filename of the subtemplate to load. This is an html file just like the main template.

Collection to repeat

“Collection to repeat” is a key indicating the contents to repeat over. It depends on the context. The valid values currently implemented are:

-“entrylist” as collection of entries relevant to the current request (either folder’s children or category contents)

-“breadcrumbs” which is a list of the current entry’s parents or the current category’s breadcrumbs

-“pager” which generates a list of page indexes given a page size parameter

-“versions” which generates a list of versions of the requested entry

-“log” which generates the log for the requested entry

-“categorylist” which generates a list of subcategories based on a requested

Parameters

Again these depend on context, but the most common is the page size parameter to allow paging.

Example

[subtemplate|Entry.html|entrylist|pagesize=10]

This will generate a list of child entries of the currently requested entry and render template “Entry.html” for each one for a maximum of 10 entries (page size).

Conditional Templates

A conditional subtemplate is defined as follows:

[subtemplate|template filename|condition|expectedvalue]

Condition

The condition is like a regular token: object:property.

Expected value

The object’s property value is compared to the value and if they match then the template is rendered

Example

[subtemplate|ViewEntry.html|entry:iscollection|false]

This renders subtemplate “ViewEntry.html” is Entry:IsCollection (which returns a Boolean and it true if the entry is a folder) evaluates to False.

CSS/JS

Whenever a template is rendered “template.css” is also emitted to the client browser. If there is a subdirectory “css” then all css files under that will also be included. Note though that for performance’s sake you should attempt to keep the number of files to a minimum so just using template.css is preferred.

The same goes for javascript files. If there is a file “template.js” it will be included. If there is a subdirectory “js” then all js files in that will be included. Again it is advisable to keep files to a minimum.

Templated JS Blocks

You may optionally include snippets of Javascript that go through the templating engine. That way you can include parameters that are in the content. To do this you:

1. Need to create a directory called “jsblocks” in the template
2. Add your snippet as .js file there

jQuery

The template view automatically requests jQuery to be included from the DNN framework.

Buttons

To help you construct a number of buttons on screen there is a special object that can be used through the ‘button’ tokens to access common functions on an entry. The token syntax is slightly different than that for others. The syntax is

[button:command_property]

The command can be New, NewVersion, Edit, Download, DownloadSelection, MailMe, AddToClipboard, ClearClipboard, MoveClipboard, CopyClipBoard, Import, Lock, Unlock, Delete, UnDelete, HardDelete, Subscribe and UnSubscribe.

The properties that can be used on the command are: url, visible, text, tooltip. Note that all commands operate on the currently viewed entry (folder or file). These buttons cannot be used in the list of entries that appear in a folder or category. The url is the url that will perform this action. ‘Visible’ returns true or false depending on whether the user can perform the action. ‘Text’ and ‘ToolTip’ finally provide localized descriptions of the action.

Example

<a href="[button:new_url]" class="document_new-png link" title="[button:new_text]" style="display:[button:new_visible|block;none];"</a>

Will display the new button if the user has permission to access this. Note the button is only hidden through css so the link could be picked up in the raw HTML of the output. The module would not allow the user to create new content though as security is checked later.

Parameters

As mentioned above we may pass in parameters to a repeating template. The currently known parameters are “pagesize”, “entrytypes”, and “permission”.

The PageSize Parameter

You can invoke paging in a subtemplate using this parameter. This parameter is only relevant to the “entrylist” and “pager” collections. There is one caveat to note here: the entrylist subtemplate must come before the pager subtemplate. The templating engine will divide the collection into pages and request the current page. The current page is set using a querystring parameter: “Page”.

The Pager Collection

When the pager is repeated 2 parameters are passed into the template: the “page” parameter which tells it which page it is and a Boolean “pageiscurrent” which tells it whether this is the selected page. These are used for example as follows:

<div style="display:[custom:pageiscurrent|inline;none]" class="pageButton">[custom:page]</div>

This shows a div is the page is the current page and has as contents the page’s number.

The Entrytypes Parameter

You can control the rendering of the subtemplate based on the type of entry you are rendering. So, for instance, you could opt to only show a subtemplate if the entry is a folder (“Collection”) or if it is a Word document (“File.Microsoft.Word”). You can specify any number of entry types by concatenating them using a semicolon as separator. E.g.

[subtemplate|BreadCrumb.html|breadcrumbs|entrytypes=Collection]

Will only render the breadcrumbs if the requested entry is a folder.

The Permission Parameter

You can opt to limit rendering the template only to users with specific permissions. Again you can concatenate them using semicolons. The following are permitted:

-“true” will always render

-“admin” will render to administrators only

-“view”, “edit”, “approve”, “add” will render if user has specified access to entry

-Other: will render if user has that application permission (“docadmin”, “webdav”, “mailing”)

For example:

[subtemplate|Log.html|log|pagesize=10,permission=admin;docadmin,entrytypes=file]

Will render the log if the user is document administrator or administrator and only if the entry is a file.

Sorting

This is only relevant to the entrylist collection. The entry list sorting can be controlled through the querystring. The following variables can be used for this:

sort / Column to sort on. Note that this column must exist in the return set of the entrylist (see entry properties below)
so / The sort order: asc = ascending, desc = descending
ft / Boolean (true/false) to keep folders at the top or not. What this does is, if set to ‘true’ then ‘IsCollection DESC,’ is injected before the sort. This will keep all folders at the top of the list.

Note you must propagate the values in the various hyperlinks you use on the template yourself. In the default template set you’ll see this done in the PageTemplate and PagerTemplate.

Annex: Objects and Properties

The following objects are at your disposal in the templated view:

entry, parent / This is the central object in DMX. The entry can be a folder, a file, or a hyperlink. It is identified through EntryID and is stored in the DMX_Entries table. “entry” is the current requested entry (EntryId in querystring). “parent” is the entry which is the parent of the current entry.
author / String
collectionid / EntryId of parent of this entry. 0 is the absolute root.
created / Date when entry was first created
deleted / Boolean
entry / If Hyperlink this is the url
entryid / Unique identifier (Integer) for the entry
entrytype / Key that identifies the type of entry. 'Collection' means it’s a folder, 'Hyperlink', a hyperlink, 'File.Xml' an Xml file, etc. Check DMX_Extensions table for full list
filesize / Long Integer
filesizeformatted / String of file size to Kb/Mb/etc
isapproved / Boolean
keywords / String
lastmodified / Date when entry was last edited
lastversionid / EntryId of the last version of this entry
lockedby / UserId of locking user
lockeduntil / Date and time until end of lock
lockkey / GUID of lock
islocked / Boolean
md5hash / String hash value of file
originalfilename / String
owner / UserID of user that uploaded entry
path / String of entry ids of path to current entry
permissionsonlybyadmin / Boolean
portalid / Integer
version / Integer of version nr
versionstokeep / Integer
title / Localized title
remarks / Localized remarks
Iscollection / Boolean
Isfile / Boolean
Ishyperlink / Boolean
Thumbnail / String value of thumbnail field
Thumbnailurl / Gets a proper url to the thumbnail (or spacer.gif if empty)
thumbnailoricon16, thumbnailoricon32 / Gets thumbnail url or correct icon (16x16 or 32x32 rendering)
Hidden / Boolean: is entry is marked as hidden (thumbnails are marked thus)
Canview / Boolean: can current user view this entry
Canapprove / Boolean: can current user approve this entry
Canadd / Boolean: can current user add children to this entry
Canedit / Boolean: can current user edit this entry
Issubscribed / Boolean: is the current user subscribed to this entry
Permissions / String of formatted permissions
Categories / String of formatted categories
icon16, icon32 / Icon value for current entry type (16x16/32x32 pixels)
icon16html, icon32html / Html blob rendering the icon correctly independent of whether it is a css sprite or a file
icon16isclass, icon32isclass / Boolean whether icon is sprite or not
fullpath / Full path to entry
folderpath / Full path to parent
entryattribute, parentattribute / Object to access custom attributes in the interface
AttName / The name is looked up in the attributes for this entry. If found the value is returned (as String)
category / A category from DMX
id, categoryid / CategoryID of category
parentid / CategoryId of the parent of the category (0 is root)
vieworder / Integer to sort the display of categories
Name, categoryname / Localized name of category
log / In the log table this is the object that refers to the entry in the log
action / Corresponds to the logtypekey of the log type ("Add", "Edit", etc)
datime / Date and time of action
entryid / EntryId of document that was the subject of the action
userid / UserID of user that performed the action
logtype / In the log table this is the object that describes the type of event that took place
logtypekey / identifier of log type
Resourcefile / Resourcefile where texts for logtype can be looked up
Phrase / The localized verb for the logtype (like 'edited', 'added', etc)
query / The query object stores information about the current request and prepares objects like the currently requested entry
Categoryid / ID nr of category being requested in the querystring (CategoryId=xx)
currentcategoryid / ID of the category being rendered (in case CategoryId is not in the querystring)
Collectionid / Entry nr of folder being requested in the querystring (CollectionId=xx)
Command / Command (Command=xyz)
entryid / Requested EntryID (EntryID=xx)
invalidrequest / Something went wrong in parsing the request
isingodmode / User is either Admin or Host
isdocadmin / User is document administrator
isowner / User has same UserID as Owner of requested entry
rootid / The RootId specified in the module's settings
subscribed / The current user is subscribed to the requested document
thisistheroot / The currently requested EntryID is the same as the RootID for the current module
viewtype / CollectionView, CategoryView, DetailsView
authenticated / Boolean whether the current user is authenticated
var=value / Boolean whether querystring value ‘var’ is equal to value.
var / Querystring value for ‘var’
dmxmodule / Several parameters relating to the context of the current module
url / Is the NavigateUrl of the current tab with a trailing ? Or & to facilitate adding parameters
rooturl / DotNetNuke.Common.ResolveUrl("~/")
moduleurl / RootUrl & "DesktopModules/Bring2mind/DMX/"
imageurl / ModuleUrl & "images/"
resources / Helper object to get localized resources
ResourceKey / This will pull the specified resourcekey out of DesktopModules/Bring2mind/DMX/App_LocalResources/ SharedResources.ascx.resx or Menu.ascx.resx
loguser / In the log table, this is the user that performed the logged action.
verificationcode / as in DNN
affiliateid / as in DNN
displayname / as in DNN
email / as in DNN
firstname / as in DNN
issuperuser / as in DNN
lastname / as in DNN
portalid / as in DNN
userid / as in DNN
username / as in DNN
fullname / as in DNN
roles / as in DNN
custom / This is used in special occasions. For now only in the pager button templates.
page / Page nr
pageiscurrent / Boolean set if page nr is currently viewed page

Note that this solution uses the DNN core token replace mechanism and you can therefore also use the module, portal, and user objects like you would anywhere else.

September 27, 2011