Category: Tutorials for xajax 0.2

Tutorials:Processing Forms with xajax

[edit] xajax.getFormValues()

xajax makes processing form data asynchronously extremely easy. The xajax.getFormValues() method can be used to automatically extract the data from a form and pass it as a parameter to a PHP function you have registered with xajax.

xajax.getFormValues() takes one mandatory argument, which can be either the id of the form you want to process, or the actual form object (see Note below). You use xajax.getFormValues as a parameter to your xajax function, like this:

xajax_processFormData(xajax.getFormValues('formId'));

where xajax_processFormData() is your function that takes the form data as a parameter.

xajax generates a query string representing the form data which is parsed by the xajax server and passed to your PHP function as an array representing the form data, just as if you had submitted the form and used the PHP $_GET array.

NOTE: Your PHP function definition must have a parameter for the array, otherwise the form variables will not be passed to the PHP function.

NOTE: Do not try to access $_GET... Your handling PHP function should look like MyFunc($dta). When it gets invoked the array of form variables will be passed in $dta and you can handle it like any other associative array. I tried $_GET to no avail. (Note to the note: you could get the data from $_POST['xajaxargs'][0] where it's encoded as an XML xjxquery tag -- but why not just let xajax make your life easier here? Besides, it could change in future versions.)

xajax will even handle complex input names to generate multidimensional and associative arrays. For instance, if you have a form with three checkboxes and you give them all the name "checkbox[]", but different values like "check1", "check2", and "check3", and you use the xajax.getFormValues function as a parameter to your xajax function, the PHP function will receive an array that looks like this:

array (
  'checkbox' => 
  array (
    0 => 'check1',
    1 => 'check2',
    2 => 'check3',
  ),
)

The array argument to your function mirrors the structure that the $_GET array would have if you were to submit the form traditionally. You can then access the checkbox data in the array like this: $aFormData['checkbox'][0]

NOTE: Make sure that you assign your forms an id in addition to a name attribute. If you have failed to assign an id to the form, Internet Explorer uses the value of the name tag for the id and the getFormValues function will appear to work anyway. Firefox, on the other hand, can't find the form unless you explicitly set the form id.

NOTE: When using Firefox, make sure to assign a name attribute to all input types that you want the getFormValues function to grab. Just an id attribute will not work.

[edit] Submitting just a part of the form

If you want only a part of the form elements to be submitted (a subset of the form), there is a new option starting with 0.2.1. There is an optional parameter to xajax.getFormValues, specifying a prefix -- if set, only form elements starting with that prefix would be submitted to the PHP function. This can be very handy when you have a large form and only want to update a subsection of it. The prefix parameter is the third parameter of the function, the first being the form's id and the second being a boolean indicating whether to submit disabled fields.

So the full syntax becomes:

xajax_processFormData(xajax.getFormValues(formID[,bSubmitDisabled[, prefix]]));