New XAP controls and File Upload

From CometWiki

Revision as of 20:18, 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[]

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 File Upload Mechanics