New XAP controls and File Upload
From CometWiki
| Line 97: | Line 97: | ||
| - | === New File Upload Mechanics === | + | === 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$ = "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. | ||
Revision as of 20:35, 13 March 2025
Contents |
New XAP Controls and File Upload
New Controls
These new controls can be added to your #XAP file, and will change how XAP builds the keyed file containing query key/value pairs.
WRITEEMPTYFIELDS
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
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[]
Array Handling for Form Elements
Starting in Comet 540, XAP supports HTML form input arrays. You can designate any <input> as an array element by including "[]" at the end of the name. Each value in a designated array will be written to a zero-indexed array using the <input> name as the key field. For example,
<input type="text" name="stringinput[]"> <input type="text" name="stringinput[]"> <input type="text" name="stringinput[]"> <input type="text" name="stringinput[]">
will display 4 text inputs in an HTML form. When submitted to XAP, the CGIFILE will contain the following key/value pairs:
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
where each key/value corresponds to the element in the order in the HTML form. In order to be backwards compatible with previous versions of Comet/XAP, we include the last Q.STRINGINPUT[] as a key without an index, and the value of the last query value specified in the form. In previous versions, this would be the only key/value defined in the CGIFILE.
Note, this example assumes that URLDECODEKEYS TRUE was included in the #XAP file. By default, the query keys will not be decoded, and your CGIFILE will look like this:
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
Using this example, if the second value is empty (no value), then the CGIFILE will contain the following key/value pairs:
Q.STRINGINPUT[0] - first value Q.STRINGINPUT[2] - third value Q.STRINGINPUT[3] - fourth value Q.STRINGINPUT[] - fourth/last value
because, by default, XAP does not write key/value pairs to the CGIFILE that have empty values. Using the new control WRITEEMPTYFIELDS TRUE will force XAP to write all key/value pairs, regardless of whether the value is empty:
Q.STRINGINPUT[0] - first value Q.STRINGINPUT[1] - empty Q.STRINGINPUT[2] - third value Q.STRINGINPUT[3] - fourth value Q.STRINGINPUT[] - fourth/last value
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$ = "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.
