File Upload Custom Control

XMod provides the File Upload control as a bonus custom control to enable your form's users with an easy means of uploading a file to your web server.

It's really two controls in one. It's both a file picker control and a file upload control. By setting the displaymode attribute, you can use the control as a file picker, a file upload control, or both. Plus, it works with DNN's list of allowable file extensions so only extensions allowed (via DNN's HostSettings page) are available to the control for potential upload. The control can further limit the types of files uploaded by setting the extensions attribute.

The control also provides a list control which lists available files in the target upload directory and dynamically refreshed after each upload. This allows your users to upload a file and then select it.

The File Upload control is customizable. Using its properties, you can filter which files can be uploaded according to their file extensions (this filter is applied after the DNN extension filter), dynamically generate unique filenames for uploaded files using a pre-defined pattern, overwrite or preserve existing files, specify an upload directory, and much more.

To use the File Upload control, you must <register> it in your form and create a <custom> tag where you want to use the control. Below are attributes of the FileUpload control. These include those attributes required by the <custom> control tag (ref, name, tagprefix, etc.)

NOTE: To use the File Upload control, you must enable custom controls in XMod. For security purposes, this is turned off by default. For information on enabling custom controls, see the "Usage Notes" section below.

ATTRIBUTES :

ref	The ID of the control, used by XMod to set the name of the field for the form. This must be unique within the form. (Required) Names must begin with a letter and may only include letters, numbers and the underscore character.
extensions	Determines which file types can be uploaded. This serves as an additional filter beyond what is allowed by DNN. Thus, if a file type is allowed here, but is not allowed by DNN, the file will not be allowed. Extension should be specified as a comma-separated list. So, to only allow images, you would specify "jpg,gif,png" as the value for this attribute. The default value is the extension list allowed by DNN. (Optional)
tagprefix	This is the prefix XMod uses to match the control with the assembly that contains the custom control (specified in the <register> tag). (Required) [String value]
name	The name of the control. This should always be "FileUpload" (Required)
cssclass	Assigns a CSS class name to the internal HTML file control. (Optional)
uploadlinktext	The text of the link the user clicks to upload the file they've selected. The default value is 'Upload'. (Optional)
uploaddirectory	The directory into which the file will be placed and the directory where the file picker portion of the control will load its list of files from. See usage notes below for important additional information. The default value is the portal's upload directory. (Optional)
overwrite	If true, a file with the same filename as the file being uploaded will be overwritten. If false, the control will generate a unique filename for the uploaded file in the case of a naming conflict by appending a number to the end of the filename. The default value is false (Optional)
namingpattern	If blank, the uploaded file's name is used. Otherwise, use this attribute to dynamically create a name for the new file. The control provides a number of placeholders you can use, along with your own text, to generate filenames. Use of the placeholders is optional. {FileUpload_FileName} Replaced at runtime by the uploaded file's name, without the extension. {FileUpload_FileExt} Replaced at runtime by the uploaded file's extension. {FileUpload_Date} Replaced at runtime by the current date in the format YYYYMMDD (i.e. 20050131 for Jan 31 2005) {FileUpload_Time} Replaced at runtime by the current time in the format HHMMSS (i.e. 132405 for 1:24:05 pm - hours are 0-23)
noneselected	If true (the default value), the control will insert "<None Selected>" as the first item in the file list. (Optional)
displaymode	(Optional) Valid values are: filelistonly - the control acts as a file picker control and does not give the user the option of uploading a file. uploadonly - the file list picker isn't shown. Only the upload control is shown. uploadandselect - this will just show the file upload control, but will store the most recently uploaded file information (as if the file were uploaded then selected in the file picker). This is helpful for allowing users to upload files without seeing other files in the directory. If not specified, the control will display the file list picker control with a link to add a new file which then displays the upload control.
uploadonce	If false (the default), users may upload more than one file. If true, users are only allowed one successful upload per editing session (i.e. when adding or editing a record). If they edit the record again, they will be allowed to upload another file. (Optional)
style	This pass-through HTML property allows you to set the CSS style properties of the control. (Optional)
addnewlinktext	This is the text displayed in the link the user clicks to display the file upload control. The default value is 'Add New File' (Optional)
listwidth	Allows you to control the width of the file piker list control in standard .NET units (pixels, points, etc.) (Optional)

USAGE NOTES

Custom Controls Must Be Enabled by the Host in order for the FileUpload control to be used. To do so, login as Host, select "Administration" from the Actions menu, and check the box next to "Enable Custom Form Controls" (in the Global Settings section). For security, custom controls are disabled by default.

Upload Directory: This directory is used by both portions of the control. Uploaded files are placed in the directory and the file list control looks at the directory to get its list of files. If this directory doesn't exist, the control will attempt to create it. This directory is relative to the portal's upload directory. So, if you specify "images", the file will be placed in the "/Portals/nn/images" directory (where nn is the portal's ID). The control will also create child directories. So, if you specify "2005/images", the control will attempt to create a "2005" directory with a child "images" directory.

Required Fields: You may encounter some problems when using the "required=true" attribute of the <input> control tag. If no value has been entered in the field, the required field validator will fire when clicking the pop-up calendar link. While this is normal behavior, it may a bit confusing for your users. There are two ways to alleviate this problem - 1) set a default value for those controls; 2) use the server-side required field validation offered as a new feature in XMod version 3 (see <validate>).

EXAMPLES

The following example registers the file upload control, then uses it via the <custom> tag. The control will display the file picker control with an "Add New File" link which, when clicked, will display the file upload control. Any uploaded file will be saved into the 2005/images subdirectory of the portal's upload directory

<form>

<label>Image Name</label>

</input>

<label>Email</label>

</input>

<label>File Upload</label>

</custom>

</controls>

</form>