New XAP controls and File Upload - Revision history

Justin at 18:36, 14 March 2025

2025-03-14T18:36:31Z

← Older revision		Revision as of 18:36, 14 March 2025
Line 156:		Line 156:
	==== Uploading Files via HTML Form ====		==== 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.	+	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.

	Example:		Example:

Justin at 18:36, 14 March 2025

2025-03-14T18:36:04Z

← Older revision		Revision as of 18:36, 14 March 2025
Line 156:		Line 156:
	==== Uploading Files via HTML Form ====		==== 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~~.	+	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.

	Example:		Example:

Justin at 18:33, 14 March 2025

2025-03-14T18:33:42Z

← Older revision		Revision as of 18:33, 14 March 2025
Line 3:		Line 3:
	=== New Controls ===		=== 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~~.	+	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 ====	+	==== WRITEEMPTYFIELDS (#XAP Setting) ====

	Force XAP to write keys to the CGIFILE even if the value is empty.		Force XAP to write keys to the CGIFILE even if the value is empty.
Line 29:		Line 28:


-	==== URLDECODEKEYS ====	+	==== URLDECODEKEYS (#XAP Setting) ====

	Tell XAP to decode special characters when writing the keys in the CGIFILE.		Tell XAP to decode special characters when writing the keys in the CGIFILE.
Line 51:		Line 50:


-	==== GET FILEDATA ====	+	==== GET FILEDATA (XAP Control) ====

	Retrieve the data from an uploaded file inside an XAP program.		Retrieve the data from an uploaded file inside an XAP program.

Justin at 21:30, 13 March 2025

2025-03-13T21:30:59Z

← Older revision		Revision as of 21:30, 13 March 2025
Line 67:		Line 67:
	filedata$ = control(0, "GET FILEDATA filename.ext")		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~~	+	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 ===		=== Array Handling for Form Elements ===

Justin at 20:51, 13 March 2025

2025-03-13T20:51:55Z

← Older revision		Revision as of 20:51, 13 March 2025
Line 50:		Line 50:
	----		----

		+
		+	==== 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 ===		=== 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,~~	+	==== 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[]">
Line 60:		Line 88:
	<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:	+	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[0] - first value
Line 68:		Line 100:
	Q.STRINGINPUT[] - fourth/last 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~~.	+	The last key, '''Q.STRINGINPUT[]''', ensures backward compatibility with older XAP versions where only the last submitted value was stored.

-	~~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~~:	+	==== 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%5B0%5D - first value
Line 78:		Line 112:
	Q.STRINGINPUT%5B%5D - fourth/last 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~~:	+	==== 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[0] - first value
Line 85:		Line 121:
	Q.STRINGINPUT[] - fourth/last 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~~:	+	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[0] - first value
Line 92:		Line 128:
	Q.STRINGINPUT[3] - fourth value		Q.STRINGINPUT[3] - fourth value
	Q.STRINGINPUT[] - fourth/last 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.


Line 130:		Line 178:
	Example Usage:		Example Usage:

-	filedata$ = "get filedata file1.xxx"	+	filedata$ = control(0, "get filedata file1.xxx")
	newpath$ = path("TMP") + "file.xxx"		newpath$ = path("TMP") + "file.xxx"
	Printfile newpath$ filedata$		Printfile newpath$ filedata$

Justin at 20:35, 13 March 2025

2025-03-13T20:35:09Z

← Older revision		Revision as of 20:35, 13 March 2025
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.

Justin at 20:18, 13 March 2025

2025-03-13T20:18:08Z

← Older revision		Revision as of 20:18, 13 March 2025
Line 4:		Line 4:

	These new controls can be added to your #XAP file, and will change how XAP builds the keyed file containing query key/value pairs.		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 ====		==== WRITEEMPTYFIELDS ====
Line 20:		Line 24:

	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.		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 ====		==== URLDECODEKEYS ====
Line 38:		Line 46:

	into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, '''Q.STRINGINPUT[]'''		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 ===		=== 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 ===		=== New File Upload Mechanics ===

Justin at 19:08, 13 March 2025

2025-03-13T19:08:15Z

← Older revision		Revision as of 19:08, 13 March 2025
Line 25:		Line 25:
	Tell XAP to decode special characters when writing the keys in the CGIFILE.		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. ~~For~~ example, '(', '[', and '%' are encoded as '%28', '%5B', and '%25' respectively.	+	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:		So if we have a input field for text named like this:

Justin: Created page with "== 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 ke..."

2025-03-12T23:55:58Z

Created page with "== 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 ke..."

New page

== 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. For example, '(', '[', and '%' 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 ===

=== New File Upload Mechanics ===