Working with Files

Documentation home

Uploading files from a browser 1

Options available with API form.uploadFileFromBrowser() 3

Creation of PDF document files 4

Creation of XML files 4

Emailing files as attachments 4

Additional programming facilities 5

API File Services 5

FPL Functions 5

 

Ebase Xi includes a number of facilities to facilitate the handling and processing of physical files. These include:

 

Uploading files from a browser

The upload facility is invoked by using the FPL upload command or the API form.uploadFileFromBrowser() method; The FPL upload command takes no additional parameters whereas the API form.uploadFileFromBrowser() method allows specification of upload options where some of the parameters can be changed. Both result in the display of the upload page as shown below. The texts in this window can be customized or displayed in languages other than English (see below).

 

  

The user can press the Browse... button to navigate to a file. The Upload button uploads the file to the server and the Cancel button cancels the upload process. Pressing either the Cancel or Upload buttons returns control to the Ebase form and processing resumes at the statement following the upload or form.uploadFileFromBrowser() statement.

 

Uploaded files are saved in the directory specified with server property Upload To Directory, but this directory can be overridden when using the API form.uploadFileFromBrowser() method (see upload options). The last portion of the file name will be the name of the file on the client machine with a number added if necessary for uniqueness e.g. the first upload of a file named my_cv.doc will be saved with this name, the second with my_cv1.doc, them my_cv2.doc etc. In addition, any spaces in the file name will be changed to underscores ( _ ) to ensure valid filenames when a Windows file is being saved on a Unix or Linux server.

 

After an upload, the $FILE_NAME system variable is set with the full path name of the uploaded file as saved on the server system. This can then be used to add the file to an email as an attachment, or it can be assigned to other form fields, or can be substituted into a message or email text, or used in any other script commands. If the Cancel button is pressed, $FILE_NAME will contain a null value.

 

In addition the $FILE_NAME_USER system variable is set with the last portion of the file name on the client system e.g. if the user has uploaded C:\My Documents\my_cv.doc, then $FILE_NAME_USER will contain the value my_cv.doc. This is provided so positive feedback can be provided to the user.

 

Here are sample scripts that can be used for uploading a single file. This script would typically be activated by an action button on an Ebase form page e.g. with text Click here to upload your CV.

 

FPL:

API based language (Javascript):

 

// sample upload script

// display the upload page...

upload;

// Processing resumes here after the upload..

// Error message if the Cancel button has been pressed

if [$FILE_NAME = null]

message 'You must upload something';

else

// Show info message if file uploaded successfully

message W, 1013, $FILE_NAME_USER;

set CV_FILE_NAME = $FILE_NAME;

endif

// end of upload script

 

Message 1013 has the text: File && uploaded successfully

 

// sample upload script

// display the upload page...

form.uploadFileFromBrowser();

// Processing resumes here after the upload..

var fileName = system.variables.$FILE_NAME.value;

if (!fileName)

{

   // Error message if the Cancel button has been pressed

   event.owner.addErrorMessage("You must upload something");

}

else

{

   // Show info message if file uploaded successfully

   event.owner.addWarningMessage(1013, [fileName]);

   fields.CV_FILE_NAME.value = fileName;

}

// end of upload script

 

Message 1013 has the text: File && uploaded successfully

 

 

Two server properties can be used to constrain the uploaded documents. When using the API form.uploadFileFromBrowser() method, these parameters can be overridden for each upload (see upload options).

 

Maximum File Size :    the maximum permitted file size for an upload. This can be specified as nnnM (megabytes) or nnnK (kilobytes) or just a number e.g. 5M or 500K or 600000 (600K). If omitted the default is 1M. Limiting the size of uploadable files helps prevent denial of service attacks where a hacker attempts to crash the server by uploading extremely large files.

 

Upload File Types : contains a comma delimited list of case insensitive acceptable file types e.g. doc,xls,ppt. Value all can also be specified and this is the default if this parameter is omitted.

 

 

!!! Important note: Ebase does not check uploaded files for viruses. Virus checking software should be installed on the server to prevent the uploading and saving of infected files.

 

The texts and messages displayed in the upload window can be customized using the Server Administration Application – System Texts Editor. These can also be specified in languages other than English. The upload window texts are shown in the table below.

 

Upload window texts (language English)

 

Text no.

Description

Default supplied text

320

Header text

Please enter the file to be uploaded in the box below or press the Browse button to navigate to the file. Then press the Upload button. Files of all types can be uploaded and the maximum permissible file size is 2MB.

321

File name label

File name

322

Upload button

Upload

323

Cancel button

Cancel

324

Trailer text

Press Upload to upload the file, Cancel to return

325

Stylesheet used for texts

See system texts editor

326

Stylesheet used for error messages

See system texts editor

327

File not found error message

Error: file is empty or does not exist

328

File type not allowed error message

Error: file type is not supported for upload

329

File too large error message

Error: uploaded file exceeds maximum size of

 

 

Options available with API form.uploadFileFromBrowser()

When invoking an upload with the API method uploadFileFromBrowser(), additional options can be specified with each upload:

 

 

Supported file types is a list of case insensitive file types supported by the server e.g. doc, pdf, txt etc. An error message is issued if the user attempts to upload a file with a different type.

 

Supported MIME types provides a way of helping the user by setting the file types in the browse panel. This is implemented using the HTML accept parameter of the input tag, and this implementation varies according to the browser with some browsers - notably IE before version 10 - providing no support at all. So using MIME types provides a way of helping some users, but it doesn’t provide a way to constrain which files can be uploaded – use supported file types to achieve this.

 

var opts = new UploadOptions();

opts.directory = "c:/temp";                                   // Backslashes should be escaped e.g. c:\\temp

opts.maxFileSize = "5M";                                     // Files larger than 5MB can’t be uploaded      

opts.acceptedMimeTypes = [ "image/*", "application/pdf" ];   // Limit the file types shown in the browse panel

opts.fileTypes = [ "png", "gif", "jpg", "pdf" ];             // Only these file types can be uploaded

form.uploadFileFromBrowser(opts);                            // Invoke the upload

 

 

Creation of PDF document files

 

PDF documents can be generated and displayed to the user in a number of ways: with one of the API WebForm.generatePdf() methods or with FPL commands outputpage, print and PDFPrint. All of these provide an option to save the generated PDF documents.

 

Creation of XML files

 

The FPL write command or API XmlResource.write() method can be used to create an XML file and system variable $FILE_NAME will contain the full path of the generated XML file after issuing this command. (See Working with XML Resources for more information)

 

Emailing files as attachments

 

Any number of files can be sent as attachments with an email message, for example:

 

FPL:

API based language (Javascript):

 

// send mail with single file attachment

sendmail JOB_APPLICATION_MESSAGE with attachments $FILE_NAME;

 

// send mail with multiple file attachments

sendmail PLANNING_APPLICATION_MESSAGE with attachments FILE1, FILE2, FILE3, FILE4, FILE5;

 

 

// send mail with single file attachment

resources.JOB_APPLICATION_MESSAGE.sendmail([system.variables.$FILE_NAME.value]);

 

// send mail with multiple file attachments

resources.JOB_APPLICATION_MESSAGE.sendmail(

  [fields.FILE1.value,

   fields.FILE2.value,

   fields.FILE3.value,

   fields.FILE4.value,

   fields.FILE5.value]);

 

 

 

Additional programming facilities

API File Services

Many services are available using static methods on the API FileServices class. This inludes creating, deleting, moving, copying, reading and writing files plus directory services e.g.

 

FileServices.createNewFile("C:/temp/test.txt");

FileServices.copyFile("C:/temp/dir1/test.txt", "C:/temp/dir2/test.txt");

var fileContents = FileServices.readFile("C:/temp/dir1/test.txt");

var xmlFile = new XML(FileServices.readFile("C:/temp/test1.xml"));         // see XML Javascript Guide

FPL Functions

The following functions can be used with file processing:

 

deletefile deletes a single file. This is an additional function and may need to be configured.

writetofile writes the contents of a form field to a file. This is an additional function and may need to be configured.

write2CSV writes contents of a form field(s) to a CSV file. This is an additional function and may need to be configured.

osfiles populates a list with the names of all files in a directory.

movefile moves a file on the server to a new location.

fileexists checks whether a file exists on the server.