New XAP controls and File Upload
From CometWiki
Contents |
New XAP Controls and File Upload
New Controls
As of Comet version 540, we have introduced new controls to enhance XAP’s support for form input arrays and file uploads. These controls are designed to improve data handling while maintaining backward compatibility. If you do not enable these new features, your existing programs will continue to function as they did in previous XAP versions, ensuring a seamless transition.
WRITEEMPTYFIELDS (#XAP Setting)
Force XAP to write keys to the CGIFILE even if the value is empty.
By default, XAP will skip writing keys to the CGIFILE if the value in the key/value pair is empty. For instance, if you have
<input type="text" name="stringinput" />
and the form is submitted with no text in the input field, then XAP will NOT write Q.STRINGINPUT into the CGIFILE.
By including
WRITEEMPTYFIELDS TRUE
into your #XAP file, even if the value in the text input is empty, there will be a Q.STRINGINPUT key in the CGIFILE, with a blank record for the value.
URLDECODEKEYS (#XAP Setting)
Tell XAP to decode special characters when writing the keys in the CGIFILE.
By default, XAP will NOT decode special characters inside the keys of the CGIFILE. Special characters include, for example, '(', '[', and '%' which are encoded as '%28', '%5B', and '%25' respectively.
So if we have a input field for text named like this:
<input type="text" name="stringinput[]" />
XAP will write the key for this input field into the CGIFILE as Q.STRINGINPUT%5B%5D
By including
URLDECODEKEYS TRUE
into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, Q.STRINGINPUT[]
GET FILEDATA (XAP Control)
Retrieve the data from an uploaded file inside an XAP program.
When a file is uploaded to XAP using the type="file" input attribute, the name is stored in the CGIFILE. For example:
<input type="file" name="myFile">
will display an HTML input element to upload a file. When a file is specified and submitted, the CGIFILE will contain:
Q.MYFILE - filename.ext
In order to retrieve the data from the upload, use the GET FILEDATA control to copy the file into a dynamic string:
filedata$ = control(0, "GET FILEDATA filename.ext")
From here you can use something like PRINTFILE to save the data to the filesystem.
Note, this method copies the entire file as a chunk of data into a dynamic string. Be aware that large files could cause performance issues depending on usage.
Array Handling for Form Elements
Overview
XAP now supports HTML form input arrays. This allows multiple values to be submitted under the same field name and stored in an indexed array. This functionality enhances data collection and processing for forms.
Defining an Input Array
To designate an input field as an array, append [] to its name attribute. Each value submitted will be stored as a zero-indexed array using the input name as the key.
Example:
<input type="text" name="stringinput[]"> <input type="text" name="stringinput[]"> <input type="text" name="stringinput[]"> <input type="text" name="stringinput[]">
This example creates four text input fields in an HTML form.
How XAP Handles Input Arrays
When submitted, the data will be stored in the CGIFILE with key/value pairs in the order they appear:
Q.STRINGINPUT[0] - first value Q.STRINGINPUT[1] - second value Q.STRINGINPUT[2] - third value Q.STRINGINPUT[3] - fourth value Q.STRINGINPUT[] - fourth/last value
The last key, Q.STRINGINPUT[], ensures backward compatibility with older XAP versions where only the last submitted value was stored.
URL Decoding of Keys
If URLDECODEKEYS TRUE is included in the #XAP file, the query keys will be properly decoded. Without this setting, the CGIFILE will store encoded keys:
Q.STRINGINPUT%5B0%5D - first value Q.STRINGINPUT%5B1%5D - second value Q.STRINGINPUT%5B2%5D - third value Q.STRINGINPUT%5B3%5D - fourth value Q.STRINGINPUT%5B%5D - fourth/last value
Handling Empty Values
By default, XAP does not write key/value pairs to CGIFILE if the field is left empty. For example, if the second input field is empty, the stored values would be:
Q.STRINGINPUT[0] - first value Q.STRINGINPUT[2] - third value Q.STRINGINPUT[3] - fourth value Q.STRINGINPUT[] - fourth/last value
To force XAP to store all fields, including empty ones, use the WRITEEMPTYFIELDS TRUE setting. This ensures all key/value pairs are written:
Q.STRINGINPUT[0] - first value Q.STRINGINPUT[1] - empty Q.STRINGINPUT[2] - third value Q.STRINGINPUT[3] - fourth value Q.STRINGINPUT[] - fourth/last value
Summary
- Use name="fieldname[]" in your <input> element to create input arrays.
- XAP stores submitted values as zero-indexed arrays.
- The last submitted value is also stored under Q.FIELDNAME[] for backward compatibility.
- Use URLDECODEKEYS TRUE to properly decode keys.
- By default, empty values are not stored; enable WRITEEMPTYFIELDS TRUE to include them.
New XAP File Upload Mechanics
Overview
XAP now supports file uploads, allowing web-enabled programs to upload and process files within the system. This feature enables users to upload multiple files and manage them dynamically.
Uploading Files via HTML Form
To upload files in XAP, use the <input type="file"> tag within an HTML form. Ensure that the enctype attribute is set to multipart/form-data for proper file handling. File uploads will ONLY work with the multipart/form-data' enctype attribute - POST will NOT work.
Example:
<form id="theform" method="POST" action="upload" enctype="multipart/form-data"> <input type="file" name="myFile[]" multiple> </form>
In this example:
- The multiple attribute allows users to select and upload multiple files.
- The uploaded file names are stored in an array for easy access.
Handling Uploaded Files in XAP
Once uploaded, your CGIFILE will store the filenames as key/value pairs as follows:
Q.MYFILE[0] - file1.xxx Q.MYFILE[1] - file2.yyy
You can retrieve the file data using the new GET FILEDATA command to copy the file data into a dynamic string and manipulate it as needed. For example, you can write it to the file system using the PRINTFILE statement.
Example Usage:
filedata$ = control(0, "get filedata file1.xxx")
newpath$ = path("TMP") + "file.xxx"
Printfile newpath$ filedata$
This command writes the uploaded file to the TMP directory while preserving the original filename.
File Management
Retrieve Data: Use GET FILEDATA to access uploaded file content.
Save Files: Utilize PRINTFILE to store files in a specified directory.
