EnhancedFile

EnhancedFile is only available for ColdFusion MX servers.

This format overcomes the problems normally associated with file upload fields within a validated form:

• The file uploaded persists after the form is validated and returned with errors to be corrected.
• A file previously uploaded may be inspected and changed, or left as is. A value may be prefilled as a default or from a database record just like any other field.
• Thumbnails of images are provided automatically. If the thumbnail is clicked, a full-size image will load in a new window.
• Files may be rejected based on size, MIME type, or extension.
• Files may be automatically added to or deleted from the permanent storage folder you specify.

Due to the complexity of its task, enhancedFile is an unusual TerraForm field in a number of ways:

• This format is actually a composite of several regular HTML fields working together behind the scenes. When a valid form is submitted, a number of values related to the file will become available on the form scope.
• This format requires the form to use the form scope.
• Unlike other TerraForm fields, which allow the format and datatype to be independent, enhancedFile is both a format and a datatype: you cannot use it as a format withut using it as a datatype, and vice versa. Here, for convenience, we are referring to it as a format.
• This format uses a temp folder on your site to store files temporarily. Simply create an empty folder somewhere within your site (it does not need to be under the web site root, but could be anywhere on your server). The folder must not contain any permanent data, such as images or ColdFusion templates. Under normal use, TerraForm will clear the entry in the temp folder after the form is successfully submitted. However, if an invalid form is abandoned after a file is uploaded, the entry in the temp folder will not be erased. Therefore, it is necessary to periodically clear out the temp folder. TerraForm will automatically clear out data older than 24 hours every time the form is displayed. You can change this setting with hourstokeeptempfile, or set hourstokeeptempfile to 0 to disable it. You will then need to write your own code to clear out the temp folder.
• As a convenience, enhancedFile will automatically add files to or remove files from your permanent storage folder. This may represent a potential security risk as a malicious user could post data to the form page including the names of other files in the storage folder, causing TerraForm to delete them. If this is a concern, leave the folder attribute blank. It will then be up to you as developer to shift the successfully uploaded file from the temp folder into the permanent storage folder, or to delete unwanted files from the permanent storage folder. See below for more information.

The following special attributes are available for EnhancedFile (many of these, such as extensionmessage, hourstokeeptempfile, maxsize, tempfolder would normally be set as a preset in your presets.cfm settings file, so that you don't need to reset them for each enhancedFile field):

• extensionlist
  Optional. List of allowed file exensions (without dots) e.g. JPG,PNG,GIF.
• extensionmessage
  Optional. Error to display in a JavaScript alert() if the extension is not allowed. This saves the user having to upload the file to receive an error message.
• mimetypelist
  Optional. List of MIME media types to allow. Each item may be a top level media type (e.g. text) or a subtype (e.g. image/pjpeg). See RFC 2046 for more about MIME types.
• maxsize
  Optional. Maximum file size in bytes. Set to 0 for no maximum.
• thumbnail
  Optional. Display a thumbnail of the file if the file is an image? Boolean, defaults to true.
• thumbnailHeight
  Optional. Thumbnail height in pixels. Defaults to 60.
• webfolder
  Required if thumbnail attribute is true. Web path to final destination of file (not the temp folder).
• folder
  Optional. Absolute path of final destination of files. If not supplied, the developer will need to shift files to and from the permanent store.
• tempfolder
  Required. Absolute path of temporary storage folder for files during the upload process. As users may abort form submission after submitting an invalid form, this folder should be periodically cleared out.
• hourstokeeptempfile
  Optional, defaults to 24. After how many hours should data in the temp folder be erased? Set to 0 to never erase it. It will then be up to the developer to manage the abandoned temp data.
• option1, option2, option3, option4, option5
  Optional. These attributes represent captions for the different activities the user chooses to perform. They default to (in order): Remove file, Revert to, Keep current file:, Use this file:, Upload a new file:. By setting these attributes, you are modifying the descriptions of the choices, not the choices themselves. For example, you could translate these captions into another language.

When this composite field is submitted with valid data, several fields will become available. If the folder attribute is not set, the developer will need to access these values to manually shift the valid file into permanent storage. If the folder attribute is set, the developer's only responsibility is to store the value in [name] (where [name] represents the name of the field). The available field values are:

• [name]
  The file name.
• [name]_action
  The action most recently performed. The following actions may occur:
  • [empty string]
    If the action is an empty string, no action has occurred. There is no file.
  • uploaded
    A file was uploaded. If the permanent storage folder has not been specified in the folder attribute, the file will still be in the temp folder. The deletion of any pre-existing file together with the move of the file from the temp folder to the permanent location will need to be handled by the developer.
  • revert
    The user selected the pre-existing file so no file was uploaded, moved or deleted.
  • clear
    The user selected to remove the pre-existing file. The file on the server is deleted. If the permanent storage folder has not been specified in the folder attribute, the file deletion case need to be handled by the developer.
• [name]_clientfile
  If a file was uploaded, the name of the file on the client.
• [name]_clientfolder
  If a file was uploaded, the absolute path to the folder containing the file on the client.
• [name]_tempfile
  If a file was uploaded, the name of the temp file in the temp folder. This will normally match the client filename.
• [name]_serverfile
  The name of the pre-existing file, if applicable, in the permanent storage folder.