File Upload Control Documentation

XMod Pro Upload Control

XMP Upload control allows file uploads through XMP. The control also provides a simple dropdown to list of files in a specified directory. The default functionality can be altered using exposed properties.

Installation

Install the provided zip file through the DotNetNuke extension manager just like a standard module. Once the installation is complete the control can be used with XMod Pro Forms.

Usage

Add the following to the top of the XMod form you wish to add the control to:

<register tagprefix="mc" namespace="xmoduploadcontrol" assembly="xmoduploadcontrol" />

You can now add the upload control to the form using the following syntax:

<mc:XModUploadControl           
    Id = "image"
    DataField = "image"
    UploadDirectory='<%#Join("~/Portals/{0}/images/", PortalData("ID"))%>'
    SaveFilePath="False"
    FilesizeLimit="2100000"  
    Extensions="*"
    IfFileExists="unique"
    View = "upload"
    ResizeEnabled="true"
    ResizeVersions = "?prepend=&append=_thumb_sm&height=100&width=100&crop=auto"
    UseAjax = "true"                                
    RemoveAction="unset"
    UploadLabelMessage = "Upload a file"
    UploadSuccessText = "File Uploaded"
    RemoveSuccessText = "Its gone"
    KeepOriginalFile="true"
    ShowThumb="false"
    SaveFileExtension="true"
    SaveResizedVersion="true"
    FilesizeErrorMessage="File is too big."
    ExtensionErrorMessage="Extension type invalid."

/>

Properties

Aside from the standard properties for XMod controls (runat, Id, DataField, DataType), the following properties can be used to modify the default functionality:

  • UploadDirectory = “Portals/0” - The directory that the files will be uploaded to. **Note that if the upload directory does not exist an error will be thrown.
  • UploadText="Upload File" - Text to show on upload button
  • RemoveText="Remove File" - Text to show on remove button
  • FilesizeLimit = “2100000”(~2.1MB) - Max filesize in bytes.
  • IfFileExists = “skip|overwrite|unique” - Action to take if the file exists.
  • SaveFilePath = ”false|true” – By default the control stored the filename rather than the full path to the file. Set this option to true to save a full path to the file.
  • Extensions = “*|.ext” – By default the upload control will accept files of any type. You can specify a space separated string to denote which extensions are acceptable. For example if you wish to allow only images the following could be used: Extensions = “.jpg .jpeg .gif .tiff .png”
  • View = “dropdown|upload|dual” – View that will be displayed.
  • RemoveAction="delete|unset" - Action to take when user removes uploaded file. Delete removes from server. Unset unsets the value but leaves the file on the server
  • NEW - UseAjax = "false|true" - *For upload view only. Allows files to be uploaded to server via AJAX. Removed the need to select a file and then click upload and then submit file. Just select file and it is uploaded.
  • NEW - ResizeEnabled = "false|true" - * For upload and dual views only. Enables image resizer on uploaded files. You must also specify ResizeVersions property to get resized images.
  • NEW - ResizeVersions = "?prepend=&append=_thumb_sm&height=100&width=100&crop=auto" - The option that you pass for each sized version of the image you want to create in query string format. Prepend/append params are used to alter filename for the version. In this example _thumb_sm is appended to the filename. Other parameters are specific to the image resizer and can be found here.You can also create as many versions as you want. Examples can be found here
  • NEW - KeepOriginalFile = "true|false" - Save the original image or not.
  • NEW - ShowThumb = "true|false" - Enables/Disables thumbnail preview.
  • NEW - SaveFileExtension = "true|false" - Setting this option to false will remove the file extension from the saved value. YOU MUST SET RemoveAction="unset" if this property is set to false.
  • NEW - SaveResizedVersion = "true|false"- This will save the first resized image in the ResizedVersions property.
  • NEW - Unzip="true|false" - This allows zip files to be deflated after upload.
  • NEW - Debug="true|false" - This displays a log that shows what happens after each request. Tests for ResizeVersions errors and configuration conflicts.
  • NEW - FilesizeErrorMessage - Error message displayed when file is too large
  • NEW - ExtensionErrorMessage - Error message displayed when file extension is invalid

EU Upload Instructions (UseAjax="false")

The following are the steps the end user must take to upload a file:

  1. Click browse button on upload control
  2. Select file to be uploaded
  3. Click upload link
  4. The message will reflect the status of the uploaded file
  5. If user has selected wrong file then they can click the remove link and repeat the upload process
  6. If successful then the user can finish and submit form

EU Upload Instructions (UseAjax="true")

The following are the steps the end user must take to upload a file:

  1. Click browse button on upload control
  2. Select file to be uploaded
  3. The message will reflect the status of the uploaded file
  4. If user has selected wrong file then they can click the remove link and repeat the upload process
  5. If successful then the user can finish and submit form

Style Elements For The Upload Control

The upload control has several classes which help customize the look of the elements of the control.

Without style, this is the basic formatting/look of the control:

Basic (no style applied)

MooreCreative XMod Pro Custom File Upload Control Basic No Style
view: dual

MooreCreative XMod Pro Custom File Upload Control Default No Style
view: upload (default)

The following are the class names to be used to add style to the upload control:

  • .xmp-uploader – wrapper that holds all the elements
  • .xmp-uploader-message – notification message
  • .xmp-btn-upload – Upload link
  • .xmp-btn-remove – Remove link
  • .xmp-filename – The textbox that displays filename once its uploaded
  • .xmp-uploader-upload – Upload input
  • .xmp-uploader-filename-label - Label to display filename once it has been uploaded.

With style applied, the upload control can have any look/style/design and for example can look like this:

MooreCreative XMod Pro Custom File Upload Control Styled

Within the example code installer, we have included a CSS Style sheet that applies some basic formatting and styles used in this example screenshot. You can also download that CSS file here: xmp-upload.css

Known Bugs/Issues

  • When using a single XMod Pro instance for a both a template and a form, UseAjax="True" will not work on DNN instances where ViewState is being cached or altered by other modules. One example of a module that does this is PageBlaster. To get around this issue the form and template must be used in 2 seperate XMod Pro instances.
  • If user cancels Forms, the uploaded files are orphaned.
  • UploadControl Extensions property is independent of DNN Host setting extension whitelist.

Token Workaround

  • Use xmp join function [[Join("~/Portals/{0}/images/users/{1}", [[Portal:ID]], [[UserId]])]]

Read The Blog!

Ideas, tips and information on what we're developing for XMod Pro!

Moore Creative's XMod Pro Blog »

Modules On Snowcovered

See all of the modules on store.DotNetNuke.com, several are free DNN modules!

Custom DNN Development

Let us build custom DNN solutions for you! l

Need Support?

Want to see a demo? Need help setting up a module or XMod Pro custom control?
Contact Us