DNN UserFiles module - Documentation

DNN User Files module: Quick Guide

Last Updated: Jan 16, 2017

Templates

Built-in templates are shipped with the product. They are saved under \DesktopModules\Evotiva-UserFiles\Templates.

User (Custom) templates are expected to be under \Portals\_default\Evotiva-UserFiles\Templates.

In any case, each subfolder of any of these roots is a template, and typically will include the files you can see now under in the default template (\DesktopModules\Evotiva-UserFiles\Templates\Default).

Some files are optional (ItemSelected.html, Template.js), and subfolders such as \Images are specific to each template (they may on may not exist, depending on each template).

Template Files

Template.html

This is the actual template, which includes everything but the list of items (files and folders) that will be displayed.

The template is that must include an element (e.g DIV) with id="evotivaUserFilesItemPlaceHolder[Module:ModuleId]" and a evotivaUserFilesItemsContainer class.  You can see examples of this in the Default template.

The element could be a DIV, TABLE, etc. It will (at run time) include the items, with the template defined  in Item.html. Therefore if divEvotivaUserFilesItemPlaceHolder is identifying a table, it makes sense for the Item.html template to define a ROW. However, if divEvotivaUserFilesItemPlaceHolder is for example identifying a DIV, the Item.html can be whatever.

Item.html

Defines how each item (files and folders) will be rendered. It must include a class evotivaUserFilesItemPane[Module:ModuleId]. You can see examples of this in the Default template.

ItemSelected.html

Defines how an item will be presented when it is 'selected' (for example, when the user clicks on it).

It is optional. If not found, the same "Item.html" is utilized.

TemplateNoItems.html

This will be rendered instead of "Item.html" when no items are found.

Template.css

CSS styles that applies to the template.

In the default template you can see classes named like ".evotiva-userfiles-..." and other named like ".evotivaUserFiles...". The first represent classes that are just in the template file(s). The second type  (".evotivaUserFiles...") represent classes that are injected by Tokens.

Template.js

Optional file for custom JS code relative to the template.

An optional OnEvotivaUserFilesDataBound(sender) function that can be implemented in this (template.js) JavaScript code file. It will be called on every data page update.

Simple example usage, to hide some content when the details are about a folder instead of a file:

Within Template.js:

function eufHideIf(hide) {
    if (hide===true) return "display: none;";
    return "";
}

Within ItemSelected.html:

    <tr style="#= eufHideIf(IsFolder) #">
        <td class="evotiva-userfiles-filedetails-label">[UserFiles:RESX|Size.Item]:</td>
        <td class="evotiva-userfiles-filedetails-text">[UserFiles:Size] ([UserFiles:SizeBytes] bytes)</td>
   </tr>

Another (a bit more elaborate) example:

    <div style="#=eufHideIf(IsFolder ||[UserFiles:DescriptionEditingDisabled]|| ItemDescription == null)#">
	    <span class="evotiva-userfiles-filedetails-label">[UserFiles:RESX|ItemDescription.Item]:</span><br/>
	    <span class="evotiva-userfiles-filedetails-text">[UserFiles:ItemDescription]</span>
    </div>

 

Advanced usage, embedding JS code directly in the template:

    <tr style="#= IsFolder ? 'display: none;' : 'display: block;' #">
        <td class="evotiva-userfiles-filedetails-label">[UserFiles:RESX|Size.Item]:</td>
        <td class="evotiva-userfiles-filedetails-text">[UserFiles:Size] ([UserFiles:SizeBytes] bytes)</td>
   </tr>

 

Template.resx

Optional file, for texts localization. (see 'Template Localization' below).

Template Localization

There are two ways to localize templates.

1. have a folder for each language. At run-time the module will pick one, with the same criteria that applies to DNN's RESX files.

For example, you can have  \MyTemplate, \MyTemplate.es-UY, \MyTemplate.es-UY.Host, \MyTemplate.es-UY.Portal-0, etc.

(see http://www.dnnsoftware.com/wiki/page/how-to-customize-edit-a-modules-language-pack)

2. keep a single \MyTemplate, and rely on its Template.resx for text localization. The same standard DNN logic applies for this Template.resx file. You can have (in the same folder) localized version such as Template.es-UY.resx, etc.

Note: Of course, if you don't need to worry about localization, you can hardcode text in the template files.

Template Tokens

Notes:

- It supports all the standard DNN tokens (see http://www.dnnsoftware.com/wiki/page/tokens)

- The tokens are not case sensitive (they can can be written in any combination of upper and lower case).

- Besides the standard DNN notation ([Object:Property],  [Object:Property|Format]), the DNN UserFiles module support the following notation:   [Object:Property|RESX:Format]. This will get the 'format' text from the active Template.resx file.

Example: [UserFiles:PageCount|RESX:PageCount].
You can see more examples of this in the Default template.

The tokens specific to this module (for which usage examples are available in the built-in default template files) are: 

Tokens relative to items' properties

[UserFiles:ItemId], [UserFiles:ItemName], [UserFiles:ItemTitle], [UserFiles:ItemDescription], [UserFiles:FolderPath], [UserFiles:LastModifiedOnDate], [UserFiles:FriendlyLastModifiedOnDate], [UserFiles:LastModifiedBy], [UserFiles:CreatedOnDate], [UserFiles:FriendlyCreatedOnDate], [UserFiles:CreatedBy], [UserFiles:Size], [UserFiles:SizeBytes], [UserFiles:Type], [UserFiles:MappedType], [UserFiles:IconUrl], [UserFiles:IconImage], [UserFiles:ThumbUrl], [UserFiles:ItemUrl], [UserFiles:ThumbImage], [UserFiles:ItemBreadCrumbs], [UserFiles:TotalItemsCount], [UserFiles:Tags], [UserFiles:TagsRaw], [UserFiles:IsFolder], [UserFiles:TagsDisabled], [UserFiles:TitleEditingDisabled], [UserFiles:DescriptionEditingDisabled], [UserFiles:TrackDownloadsDisabled]

About 'raw' data values

Besides these tokens, in JavaScript expressions you can reference raw data values directly. This could be useful for some advances usages. For example, to implement some functionality related with the file's permissions, etc.

The following data values are available: IsFolder, ItemID, ItemName, ParentFolderID, FolderMappingID, FolderProviderType, FolderPath, LastModifiedByUserID, CreatedByUserID, LastModifiedByUserName, CreatedByUserName, LastModifiedOnDate, CreatedOnDate, FriendlyLastModifiedOnDate, FriendlyCreatedOnDate, Size, SizeBytes, Type, Permissions, IconUrl, ThumbUrl, BreadCrumbs

About date tokens

Date fields can accept the following formats: F, d, D, t, T, F, M, m, s, Y and y.

Example output of each format:
  F = Saturday, May 03, 2014 7:06:54 PM
  d = 4/26/2014
  D = Saturday, May 03, 2014
  t = 7:24 PM
  T = 7:24:26 PM
  M = April 26
  m = April 26
  s = 2014-05-03T19:06:54
  Y = May, 2014
  y = May, 2014

Building a custom date-time format

You can also specify a custom format. For example: [UserFiles:LastModifiedOnDate|dd MMMM yyyy hh:mm tt]

d Represents the day of the month as a number from 1 through 31. A single-digit day is formatted without a leading zero
dd Represents the day of the month as a number from 01 through 31. A single-digit day is formatted with a leading zero
ddd Represents the abbreviated name of the day of the week (Mon, Tues, Wed etc)
dddd Represents the full name of the day of the week (Monday, Tuesday etc)
h 12-hour clock hour (e.g. 7)
hh 12-hour clock, with a leading 0 (e.g. 07)
H 24-hour clock hour (e.g. 19)
HH 24-hour clock hour, with a leading 0 (e.g. 19)
m Minutes
mm Minutes with a leading zero
M Month number
MM Month number with leading zero
MMM Abbreviated Month Name (e.g. Dec)
MMMM Full month name (e.g. December)
s Seconds
ss Seconds with leading zero
t Abbreviated AM / PM (e.g. A or P)
tt AM / PM (e.g. AM or PM
y Year, no leading zero (e.g. 2001 would be 1)
yy Year, leadin zero (e.g. 2001 would be 01)
yyy Year, (e.g. 2001 would be 2001)
yyyy Year, (e.g. 2001 would be 2001)
K Represents the time zone information of a date and time value (e.g. +05:00)
z With DateTime values, represents the signed offset of the local operating system's time zone from Coordinated Universal Time (UTC), measured in hours. (e.g. +6)
zz As z but with leadin zero (e.g. +06)
zzz With DateTime values, represents the signed offset of the local operating system's time zone from UTC, measured in hours and minutes. (e.g. +06:00)
f Represents the most significant digit of the seconds fraction; that is, it represents the tenths of a second in a date and time value.
ff Represents the two most significant digits of the seconds fraction; that is, it represents the hundredths of a second in a date and time value.
fff Represents the three most significant digits of the seconds fraction; that is, it represents the milliseconds in a date and time value.
ffff Represents the four most significant digits of the seconds fraction; that is, it represents the ten thousandths of a second in a date and time value. While it is possible to display the ten thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds.
fffff Represents the five most significant digits of the seconds fraction; that is, it represents the hundred thousandths of a second in a date and time value. While it is possible to display the hundred thousandths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds.
ffffff Represents the six most significant digits of the seconds fraction; that is, it represents the millionths of a second in a date and time value. While it is possible to display the millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds.
fffffff Represents the seven most significant digits of the seconds fraction; that is, it represents the ten millionths of a second in a date and time value. While it is possible to display the ten millionths of a second component of a time value, that value may not be meaningful. The precision of date and time values depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds.
F Represents the most significant digit of the seconds fraction; that is, it represents the tenths of a second in a date and time value. Nothing is displayed if the digit is zero.
: Represents the time separator defined in the current DateTimeFormatInfo..::.TimeSeparator property. This separator is used to differentiate hours, minutes, and seconds.
/ Represents the date separator defined in the current DateTimeFormatInfo..::.DateSeparator property. This separator is used to differentiate years, months, and days.
" Represents a quoted string (quotation mark). Displays the literal value of any string between two quotation marks ("). Your application should precede each quotation mark with an escape character (\).
' Represents a quoted string (apostrophe). Displays the literal value of any string between two apostrophe (') characters.
%c Represents the result associated with a c custom format specifier, when the custom date and time format string consists solely of that custom format specifier. That is, to use the d, f, F, h, m, s, t, y, z, H, or M custom format specifier by itself, the application should specify %d, %f, %F, %h, %m, %s, %t, %y, %z, %H, or %M. For more information about using a single format specifier, see Using Single Custom Format Specifiers.

The 'friendly' flavor of a token will render a human-friendly relative date, such as "just now", "yesterday", "2 weeks ago", etc. These texts are localized in the template's "Template.resx" file.

The "Size" is also friendly, providing texts such as "10 KB", "4 GB", etc.; while the "SizeBites" provides the raw file's size expressed in bytes.

The "TotalItemsCount" token is useful when you want to show the downloads count for the file (when you have the 'downloads traking' feature enable in the module's settings page.

About the 'MappedType' token

It is ideal to simplify and optimize (minimize) the requests sent to the server, mapping multiple file types to fewer definitions, which can be utilized, for example, as the name for a CSS class related with an image. Example (from the default template):

<div class="evotiva-userfiles-sprite-media evotiva-userfiles-sprite-media-
[UserFiles:MappedType|default=file;null=folder;jpg,jpeg,gif,png,tif,tiff,bmp,ico=image;
avi,mpg,mpeg,mov,mp4,3gp,divx,fla,flv,swf,Rmvb,wmv,vob=video;
mp3,aif,aiff,arm,wav,mid,midi,wma,ogg,rm=audio;
zip,rar,arj,ace,7z,cab,gz,jar,iso,tgz=archive;
pdf,doc,docx,xls,xlsx,ppt,pptx,pps,ppsx,rtf,txt,xml=document]">
</div>

It means: 

Unless a specific match is found, use 'file' (i.e., it is the default value).

Use 'image' for the file types jpg, jpeg, gif, png, tif, tiff, bmp, and ico

Use 'video' for the file types avi, mpg, mpeg, mov, mp4, 3gp, divx, fla, flv, swf, rmvb, wmv, and vob

etc. (it does the same for 'audio', 'archive', and 'document'.

Please notice this is just an example. You can use this token in any other way and defining whatever 'categories' you want to be utilized in any way (even from javascript code in the template's "Template.js" file.)

Tokens relative to items's sorting links

[UserFiles:ItemIdSortLink], [UserFiles:ItemNameSortLink], [UserFiles:ItemTitleSortLink],[UserFiles:LastModifiedOnDateSortLink], [UserFiles:LastModifiedBySortLink], [UserFiles:CreatedOnDateSortLink], [UserFiles:CreatedBySortLink], [UserFiles:SizeSortLink], [UserFiles:TypeSortLink]

Paging Tokens

[UserFiles:PageFirst], [UserFiles:PagePrev], [UserFiles:PageLast], [UserFiles:PageNext], [UserFiles:NumericPager], [UserFiles:PageCount], [UserFiles:PageSize]

An example, when combined with the RESX option: [UserFiles:RefreshFolder|RESX:RefreshFolder]

General Tokens

[UserFiles:RESX:|key] gets a text from the template's "Template.resx" file. Example: [UserFiles:RESX|ItemName.Item]

[UserFiles:BreadCrumbs]: the current path (where each referenced folder name is clickable).  It is the same that "ItemBreadCrumbs", except that is can be utilized in the "Template.html" file ("ItemBreadCrumbs" can be utilized in the "Item.html" or "ItemSelected.html" templates)

[UserFiles:SearchTextBox], [UserFiles:SearchTagsBox] and [UserFiles:SearchButton]: provide the UI for the user to search/filter the files (by name, content, tags, etc.). NOTE: Search by tags can be enabled only when 'Advanced Search' is enabled.

[UserFiles:TagsDisabled], [UserFiles:TrackDownloadsDisabled], [UserFiles:TitleEditingDisabled], [UserFiles:DescriptionEditingDisabled],: true when the corresponding feature is enabled in the module's settings.

[UserFiles:QueryString|something]: being 'something' whatever key of your choice, found on the query string (URL). It is ideal to be utilized in the 'Pattern' setting to alter the root path based on a querystring value of your choice.

Actions Tokens

[UserFiles:RefreshFolder], [UserFiles:AddFolder], [UserFiles:Download], [UserFiles:Delete], [UserFiles:Upload], [UserFiles:EditDate], [UserFiles:GetUrl], [UserFiles:EditTags], [UserFiles:EditName], [UserFiles:EditTitle], [UserFiles:EditDescription], [UserFiles:Properties]

There is a variation available for the [UserFiles:Download] token: [UserFiles:Download|ITEM:xxx]
xxx can be any of the supported properties. ItemId, ItemName, ItemTitle, FolderPath, Size, SizeBytes, Type
This means that you can turn any of these properties a download URL.

Some examples of the possible variations of the download token:

    <div class="evotiva-userfiles-download">[UserFiles:Download]</div>
    <div>[UserFiles:Download|Download File]</div>
    <div>[UserFiles:Download|RESX:FileDownload]</div>
    <div>[UserFiles:Download|ITEM:ItemName]</div>

The first example, is utilized in the default template. The CSS class will show an image users can click to download the file.
The 2nd. example, uses the hardcoded 'Download File' text for the download link.
The 3rd. example instead of a hardcoded text utilized localized text (found in the template's Template.resx file).
The 4th. example uses the File's Name for the download link.

Using the Module

- As Host or Admin some additional settings will be available on its settings page.

- If a 'pattern' was configured, the module will create at run-time all the missing folders. They will inherit their permissions form its parent folder.

One exception to this is when 'enable uploads' is active. In this case, the final (lower level) folder will not include permissions for 'all users', and will include read and write permissions specific for the current user. This is ideal when the pattern is utilized to create user-specific folders (example pattern: "[Module:FriendlyName]/[User:Username]") . This behavior ensures that only the user (besides host and admins) will have access to their own folder.
Notice that from the DNN File Manager you can always change the folder's permissions in the way you like.

About the "Root Folder Pattern" Setting

In this setting, you can define additional items (static and dynamic) that will be added 'at runtime' to the root folder that was defined. It supports tokens, such as [User:...], [Profile:...], [Module:...], [Tab:...], etc.

For user's Profile properties to work properly, when defining the property (in DNN Admin > Site Settings > User Account Settings > Profile Settings), remember to make it visible to the user. Otherwise, at runtime the token cannot be solved by DNN.Besides, please notice these DNN profile properties does not work for "host" accounts.

Advanced Search

When enabled, you'll be able to search by content, besides the file's basic properties. Search by Tags will be also enabled.

Textual extensions like html and txt are parsed directly. Docx files are natively parsed, without needing any external component. Binary files (pdf, doc, dot, rtf, csv, xlt, xls, xlsx, ppt, pptx, etc.) are parsed via IFilters. Therefore, the proper IFilter parser needs to be installed on the web server.

Search Criteria

One or more words can be specified if intended to obtain search results containing Files with either the first term or any of the other terms.

If a complete word is not know or more than one File containing certain information needs to be found, an asterisk (*) wild card can be used to match words starting with a specific sub-string. Wild card and non-wild card terms can be mixed in the same search.

Phrases can also be specified using double quoted text. Quoted and non-quoted terms can be used in the same search.

Some examples:

Query Explanation
conference Search for word "conference".
"conference room" Search for phrase "conference room".
conf* Search for any word that starts with "conf".
conference room Contains the word conference or room, or both.
conference OR room Contains the word conference or room, or both. NOTE: OR must be in uppercase.
+conference +room Contains both conference and room.
conference AND room Contains both conference and room. NOTE: AND must be in uppercase.
+conference -room Contains the word "conference" and not "room".

 

When adding Tags to the search query, the matching files will have all the specified tags and all the specified term expressions.

You can also search by tags only, leaving blank the terms textbox. Furthermore, in you template you can the terms search text box, and/or the tags search text box, or even none of them.

In addition, in the module's Settings Page you can specify pre-filters by tags, file extensions, and other criteria.

IFilter Prerequisites

Creating and Managing Shared URLs

When enabled (Module's Settings > Advanced > 'Enable URL Sharing?'), 'Shared URLs' creation and management will be available in any file's 'Get URL' dialog.

The shared URL will be ruled by the restrictions set when configuring it. It doesn't matter where the shared file physically is (local to the web server, or remote, handled by any folder provider such as S3, UNC, FTP, Box, OneDrive, SharePoint, Azure, DropBox, etc. included in DNNGlobalStorage or any other folder provider)

Configuration options for Share URLs:

  • Anyone can download the file, or registered users only.
  • The URL can be password-protected. In this case, the password can be provided directly in the shared URL adding '&password=the-right-password-goes-here', or it will be requested by the system if it is invalid or missing from the URL.
  • An 'Expiry Date' can be set. The link will work up to the configured date
  • It can be defined how many times the URL can be utilized. For example, you can create a URL valid for a single time, or 10 times, etc.
  • Any of these options can be combined.

From the 'Manage Shared URLs' button, a page where all the URLs created for a file and its detailed usage is displayed.

Remarks:

  • Even when an URL created with this tool is supposed to be valid (i.e. none of the possible limitations set (if any) are active), the Shared URL will not work if in the module 'Downloads' are disabled or 'Enable URL Sharing?' is disabled.
  • 'Shared URLs' will bypass DNN permissions set in the web site on pages, modules and/or folders. That's the point of this kind of share.
  • The single exception to the previous rule applies when 'Allow Anonymous Downloads' is disabled. In this case, the URL will redirect the user to the portal's login page. The download will work for any registered user.
  • Users with permission to 'Get URL' (except unregistered users) and with 'write' permissions in the folder, are able to create shared URLs and manage only their own file's shares.
  • Module's editors with 'Get URL' permissions can see and manage any user's shares.

Getting the latest version of the Module

The latest version of the module is always available for download at http://www.evotiva.com/Downloads.

Installing the Module

Install the module on your DNN portal as any other standard module, from Host > Extensions.
In the http://www.evotiva.com/Products/DNNUserFiles/Demo-Videos page, you can find a demo video showing how install the module and apply your license key.

Installing the the License Key

Manual Process

Request the License

Before installing the license key, you have to email us to licensing at evotiva.com requesting your key.
Please use the "Activation" link available on the module's Settings page, and don't forget to include your invoice number in the request.

Install the License Key

Once you get the license from us, please install your it by visiting the module's settings page.
In the http://www.evotiva.com/Products/DNNUserFiles/Demo-Videos page, you can find a demo video showing how install the module and apply your license key.

Auto-Install the License Key

Optionally, you can rename your license key (sent as a TXT file) as Evotiva.DNNUserFiles.LicenseKey.resources, and save it in the /Portals/_default folder.
The key will be auto-installed the next time you visit the page where the module is. You can verify it if was installed visiting the module's Settings page, and reviewing the License Settings section.

Choose your Evotiva-DNNUserFiles Option:

Or purchase it at the DNN Store

Testimonials

5.0 review rating David S says...

quote Good module that allows us to store all media files in Amazon S3 instead of on the web server. Support has been very responsive and effective when needed.

more reviews...