New XAP controls and File Upload

From CometWiki

Revision as of 20:51, 13 March 2025

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[]

GET FILEDATA

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")

Note, this method copies the entire file as a chunk of data into a dynamic string. If the file is large, then further copies or manipulation of the string

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.