FileBox

Top  Previous  Next

FileBox is a Process Field. It can be used inside or outside of a ProcessRecord Element.

It is used to provide file upload functionality on pages. An user can select a file from his local computer and upload to a predefined location on the server computer.

FileBox encloses a read-only text input and a button elements. The text input element contains the name of the file on the server computer.

  <span mo:type="FileBox" mo:field="true" mo:name="FILENAME" 
       mo:props="
          uploadId        : 'x123', 
          allowedExts     : '.gif;.jpg', 
          onFileSelectHandler : OnFileSelect, 
          onFileUploadHandler : OnFileUpload, 
       /* File Upload Window Properties */  
          winUrl          : '', 
          winWidth        : 400, 
          winHeight       : 130, 
          winToolBars     : false, 
          winScrollBars   : false, 
          winLocation     : false, 
          winStatusBar    : false, 
          winMenuBar      : false, 
          winResizeable   : false,
       /* Validation Properties */  
          nonBlank        : true, 
          valHandler      : MyValHandler, 
          valErrorHandler : MyErrorHandler
       ">
    <input name="pf_FILENAME" type="text" readonly="readonly" value="{FILENAME}" />
    <input name="PopWindowUp" type="button" value="Upload..." 
           onclick="FileBoxMgr.openFileDialog(this);" />
  </span>

See FileBox Function Class In the MoreMotion Face API.

When the user clicks on [Upload...] button, a File Upload Window pops up where a file from local computer can be selected and uploaded to the server.

If the [Browse...] button is clicked on the File Upload Window, the browser opens a file dialog where the user selects the file to be uploaded. After the selection is made, the selected file can be uploaded to the predefined location on the server by pressing the [Upload] button.

When the upload is completed successfully, the name of the file on the server is returned to the FileBox element that is located in the underlying  window. If, for any reason, the upload is not successful, the name of the file is not returned.

Note: The returned value is the pure name of the file with extension on the server; not the full path.

 
Required Javascript File

This element requires that the following javascript files are linked to the page in the HEAD section of the HTML document as follows.

  <head> 
    ...
    <script type="text/javascript" src="moremotion/face/Filer/Filer.js"></script>
    <script type="text/javascript" src="moremotion/face/_resources/<language-code>/Filer.js"></script>
  </head>

 

Properties

uploadId

This property should provide the name of the fileUpload configuration element. See File Upload Configuration.

allowedExts

If an extension list (items separated with ';' character) is defined in this property, the file selected through the browser's file dialog will be checked against it and the if the extension of the selected file is not in the list then uploading of it will be blocked.

onFileSelectHandler

The javascript function defined with this property is called right after a file is selected through the browser's open file dialog. If tis function returns false then the uploading of the file is canceled.

Example:

  function CheckFileName(fileName) {

    // ...

    if (...) {

      alert("Invalid file!");

      return false;

    }

  }

onFileUploadHandler

The javascript function defined with this property is called after the upload is completed successfully. This function receives the local name of the uploaded file as the parameter.

Example:

function SetImageSource(browserFileName) {

 

  var img = document.getElementById("IMAGE");

  img.src = value;

 

}

 

File Upload Window Properties

These properties are related to the window that is opened when the [Upload...] button of the FileBox is clicked.

winUrl

The URL for the File Upload Window. If no value is given to this property the default is

display.doms?pg=/moremotion/Filer/FileUploadWindow

You can copy and modify "ROOT/moremotion/Filer/FileUploadWindow.xsl" to develop your own file upload windows and specify its name in this property.

other properties

The other File Upload Window properties define the physical characteristics of the File Upload Window. Since their meanings are obvious there is no need to give additional explanations for them.

 
See Validation Properties

 

File Upload Configuration

In order FileBox to work there has to be a fileUpload definition in a global configuration file as follows.

  <fileUpload name="/x123">
    <sizeLimit>2000</sizeLimit>
    <location>WEB-INF/MM-INF/~tempfiles</location>
    <namingMethod>1. Identical With Local</namingMethod>
    <overwrite>true</overwrite>
  </fileUpload>

The name of the configuration element should be unique in the whole application and it must be specified in the uploadId property of the FileBox field.

sizeLimit (Accepts MScript)

It is possible to avoid uploading of the big files by defining a file size limit in kilobytes in this property. If a limit is defined then the upload service of the Filer component (org.moremotion.mmcomp.filer.upload.FileUploadService) will check the size of the uploaded bytes during the upload and if the limit is exceeded it will stop the uploading and delete the current file on the server.

location (Accepts MScript)

The name of the upload directory on the server computer. The definition can be absolute or relative to the root directory of the web application. If no value is given then the files are uploaded directly to the root directory of the web application.

Temporary File Uploading:

If the file to be uploaded supposed to be temporary and be deleted after a certain time, then this property should be assigned 
"WEB-INF-MM-INF/~tempfiles". MoreMotion scans this special directory all the time and deletes the expired files.

But that alone is not sufficient. MoreMotion scans only the files whose names have a value in YYYYMMDDHHMMSS pattern in their first 14 characters. If the time specified with this 14 characters is already passed the file is deleted.

To organize the name of the file using this pattern easily, the namingMethod property should be set to 2 or 3. This ensures that the file is named to be deleted after one hour.

Examples:

documents

documents/@vof(mor.Security.userName())

/usr/local/etc/documents

WEB-INF/MM-INF/~tempfiles

 

namingMethod (Accepts MScript)

The name of the file on the server is constructed according to value of this property. The choices are:

1.Identical With Local
The file name on the server will be identical to the local file name .
2.Auto-generated
The name of the server file will be an auto-generated name that has the extension of the local file.
3.Auto-generated + Local File Name
The name of the server file will be a combination of an auto-generated name and the local file name.
4.Local File Name + Auto-generated
The name of the server file will be a combination of the local file name and an auto-generated name.
 

overwrite (Accepts MScript)

If the file to upload already exists on the server the uploading is either canceled or the server file is overwritten with the new file depending on the value of this property. true means overwrite the existing file and false means cancel the upload.