Objects  >  FileUploader
Search

Module: Editor

Version: 4.4.0 +

User: Developer

Object Type: Output Object

Parent of:

No children

Child of:

- WebPage

- WebPanel

 

Description

The file-uploader is a Futurama object that can be used to allow a user to upload personal information from a file on their local system. This information can for example be used in a website application build with Futurama. Technically after uploading a file, the content of this file will be set to an UserVariable as a textstring.

Properties

AllowedContentType

This property contains the type of data that the uploaded file should contain. The selection of this value will indicate how the file content will be written to the uservariable. Binary data will be base64 encoded, while text will be written as characters. If the selected value is "text", then only files with the correct binary encoded can be uploaded, because otherwise illegal text-characters would be included. This will be prevented, so when a JPG file is uploaded while this property is set to "text", then an error is shown, and no data will be uploaded to the UserVariable.

DebugLogMode

Indicates the level of detail of debug information that is logged during runtime of the website to the trace, a logfile, a database etc. The possible values are:

  • None: no debug information is logged
  • Simple: only basic information is given
  • Extended: in addition to the information in the Simple mode the values of all the properties of the object are shown

Enabled

Possible values are 'True' or 'False'. If the value is 'False', then the object can not be used within the application.

IsPublic

Possible values are 'True' or 'False'. If the value is 'False', then the object can only be used within the document where it is created. If the value is 'True', then also from other Futurama documents can be referred to this object. This means that changes in the object also affect the document in which is referred to this object. If the value is 'True' and you attempt to move or delete the object, a warning will be given. To limit these warnings to a minimum it is recommended to set IsPublic to 'True' only when necessary.

ToolTip

In the property Tooltip a text can be entered that is shown in the application when a cursor is moved across the FileUploader. In this way information about the usage of the FileUploader can be given to the user.

UserVariable

Here you should select the UserVariable that will contain the content of the uploaded file. When a user uploads a file, the UserVariable linked to the FileUploader will hold the value entered. This UserVariable can then be used in the calculations, actions, etc. in your application.

Caution: If an XmlNode is used to read the content of the UserVariable (by selecting the UserVariable at the 'Source' property of an XmlNode), then make sure the default value of the UserVariable contains the following empty XML structure:

<UploadedFile Filename="" MimeType="" Timestamp="" IPAddress=""><![CDATA[]]></UploadedFile>

This will prevent the XmlNode giving an error, because it cannot read the contents of an XML node if the UserVariable doesn't contain any.

Visible

Possible values are 'True' or 'False'. If the value is 'True', the object will be rendered and therefore displayed in your application. If the value is 'False', the object will not be rendered.

AutoPostback

This property indicates whether the FileUploader should postback immediately after the user selects a file, or whether a seperate submit button should be used to actuate changes to the underlying UserVariable.

XmlName

The name of the object as it is shown in the source of the website. By default the XmlName is equal to the name given in the property (Name) with spaces replaced by underscores, but you are free to change it.

(Name)

The name of the object.

Comment

Here a comment can be entered. For example a short description of the object.

ID

The unique identification number of the object. This number is automatically generated by Futurama on the moment of creation. This number can be used when searching for a certain object in the Find Window

CssClass

Here the CssClass can be entered. In the stylesheet you can define the style elements that belong to this class. When this or the text-property are used, then the default appearance of the fileuploader will change into a HTML-div element. This will render the object as a block, and will allow all css styling to be applied to said DIV-element.

CAUTION: As soon as the CssClass property is filled, the original graphics will be made invisible. So it is important to provide an alternative graphical representation, otherwise the file uploader cannot be used.

Text

If the default appearance of the fileuploader does not suffice, a custom button can be made. This can be done by setting this text to generate a simple button with the provided text. This will however render the button as a HTML-div, and requires some CSS formatting to set the button's appearance beyond the default look.

Usage

When a file is selected by the user, a submit action must be triggered. This can be done with another WebControl, like a Button. After this submit action, the UserVariable is filled with text in XML format. In order to use this data an XmlNode and XmlFields can be used to access the desired fields. An example of UserVariable contents can be seen below:

<UploadedFile Filename="myFile.txt" IPAddress="127.0.0.1" MimeType="text/plain" Timestamp="2013-04-17T16:27:22.4310541+02:00">
<!--[CDATA[This file contains some simple text.]]-->
</UploadedFile>

The file content is stored in a CDATA element, and can be accessed by using the XPath text() function, for example "/UploadedFile/text()" to access the raw file content as a text string in the sample above. The data also contains the original file name, the (mime)type of the file, the time and date of the moment of uploading, and the IP-address that uploaded the file. If for example an XML-file has to be uploaded, then the 'This file contains some simple text.' of the example above is replaced by the content of the XML-file.

Filesize limits

By default, the size limit for uploaded files is limited by the maximum HTTP request length, which is set to 4 Megabytes by default. This maximum request size can be changed by setting the following code within the system.web element of the web application's web.config file, which will allow the uploading of larger files:

<!-- maxRequestLength is in kbytes with maximum of 2Gb -->
<httpRuntime maxRequestLength="20480">
<!-- Set to 20 megabytes-->
</httpRuntime>

Customizing the appearance of the FileUploader

When no CssClass or Text is provided, then the FileUploader will be rendered as a default file upload control, which is a browser-dependent appearance. Should this not suffice, a number of options exist.

  • A button can be made by setting the Text property, this will render the FileUploader as a Button with the provided text within a Div-block.
  • If only the CssClass is provided, then the appearance of the surrounding DIV block can be customized, including the background image, height, width, etc.
  • When setting both the Text and CssClass properties, one can customize the button appearance as well using CSS. The container DIV can be accessed through the CssClass, while the button can be accessed by creating a rule with the selector ".MyCssClass input[type="button"]".

Basic Example

The following example shows the basic usage of the FileUploader webcontrol.

Download

Download the Futurama Document FileUploader Basic Example.

Description

  1. Open calc.xml which is contained in the zip-file in the Futurama Editor (Version 4.4.0 or later).
  2. Within the webpage node are 4 objects: The FileUploader, a submit button that starts the file upload, a linebreak, and an WebLabel that will show the number of textcharacters in the uploaded file.
  3. In the document node are the WebPage object, a UserVariable that will contain the upload data, an XmlNode that can extract data, and a formula 'charcount' that can calculate the number of characters in the file text.
  4. The UserVariable contains an empty XML structure as a default value, to prevent errors from the XmlNode trying to read an empty string.
  5. When the page is loaded in Futurama Web, and opened in a browser, the user can select a text file.
  6. After pressing the submit button, the file is uploaded to Futurama, which will fill the UserVariable.
  7. The output label will be loaded by executing the charcount formula.
  8. The charcount formula will calculate the length of the filedata XmlField.
  9. The filedata XmlField will parse the Xml structure that can be found in the filled UserVariable containing filedata and some extra information.

Advanced Example

The following example shows the advanced usage of the FileUploader webcontrol.

Download

Download the Futurama Document FileUploader Advanced Example.

Description

  1. Open calc.xml which is contained in the zip-file in the Futurama Editor (Version 4.4.0 or later).
  2. This sample contains a similar structure to the earlier basic sample, but now contains 2 webpages. Both have a special graphical representation, namely the first consists of a custom button, while the second one consists of a HTML div object that can function as a imagebutton. Both fileuploaders upload any selected files as base64 encoded binary data into the 'data' UserVariable.
  3. The submit button in the earlier sample is replaced by enabling "autopostback" in both FileUploaders. When a user selects a file within the browser, the content is automatically submitted to Futurama, and the result will be shown directly.
  4. The charcount formula is replaced by checksum formula, which calculates a base64 encoded hashcode out of the binary data in the filedata XmlNode.
  5. The button fileuploader contains a Text property, which will render the fileuploader as a single button with the provided text.
  6. The image fileuploader is customized by setting the "uploader" CssClass to an class specified within the file "style.css". The usage of this CSS file is configured by setting the StyleSheet property in the containing webpage object. The "uploader" CSS class specifies that the FileUploader's DIV element must be 32x32 pixels in size and have a background image "folder.png". It also specifies a gray background color, and an outset border.

XML Upload Example

In the following example is based on the Basic sample, and shows the uploading of an XML file to read a certain data field.

Download

Download the Futurama Document FileUploader Xml Upload Example.

Description

  1. Open calc.xml which is contained in the zip-file in the Futurama Editor (Version 4.4.0 or later).
  2. The document is similar to the Basic sample, but instead of a charcount formula there is a new XmlNode (fileXmlNode).
  3. The new XmlNode tries to parse the filecontent within the original XmlNode (uploadedFile). The default value for the uploaded file has been extended to include a dummy XML structure within the CDATA node, so that no errors will occur.
  4. The sample zip file also includes a demonstration XML file, which can be uploaded.
  5. When an XML file is uploaded containing addresses elements (such as the included demo file), the webpage will show the content of both of them by outputting the result of the new XmlFields.

Related Topics

- Futurama Objects: The Atlas chapter that describes all Futurama objects. See the Output-section for a description of the type of objects this object belongs to.

- UserVariable

Updated: 2013-05-31
Home   |   About   |   Installation   |   Editor   |   Formulas   |   Objects   |   Vision References   |   Vision   |   FICO   |   Web API   |   Tutorials   |   Miscellaneous
Futurama Support Site