=====Abstract=====

Please provide a short abstract why we need a revised, Ajax-based page submition process...

=====Issues That Are Currently Not Being Addressed=====

1) Would it be possible to re-submit a form, that was already submitted via Ajax if the user hits <F5> or the browser's reload button?
1) Errors that may happen during the form submition process must always be alerted to the user (i.e. an alert message). Not telling the user that something went wrong, is simply wrong!
1) There must be a convenient way to disable Ajax for debugging purpose

=====Issues That Are Currently Addressed Somehow But May Need To Be Changed=====

1) Associate an error message with a HTML field name. ATM: Use an array with two items a) the field name and b) the error message
1) Disable Ajax. ATM: Put a variable name into the users Session, which triggers Ajax to be disabled (URL param: ajax_disabled=true)
1) Don't serialize disabled fields while submitting them via Ajax. ATM: Prototype handles this already
1) Associate a mousover tooltip to each HTML field, that contains wrong data

=====Revised Form-Submit Process Flow=====

1) if a form is submitted, ajaxFormSubmit() is called, the form doesn't do anything
1) it serializes the form's field values (disabled fields are excluded)
1) the form gets disabled, while the ajax request runs (e.g. the submit button and any other visible HTML input field/button)
1) a "please wait" message pops up, the elapsed time is shown (please provide a sample here e.g. an URL with a corresponding visual FX)
1) the data is send to the page itself or another page using POST(default) or GET
1) the page validates the input (no changes needed) and collects a list of errors
1) if there are errors for a specific field values, print an error (fieldname, message pairs) (ex.: "ntp_port|Please specify a valid port...") This is valid too: "field_X|Field X mustn't contain | characters ..."
1) otherwise a default or, if available, a customized success message is output'ed ("Saved and restarted xxx.")
1) now the request itself is complete and the counter stops
1) the messages are parsed by ajaxFormSubmit and printed to the info box
1) if there were errors, all corresponding fields are highlighted, get an exclamation mark image and are shaken
1) we're done now, the form gets enabled again

=====Possible Issues Which May Arise=====

====JavaScript Visual FX====

- may slow down the browser
- may confuse to user (e.g. wrong field turns red + gets and exclamation mark + gets a tooltip with an error descr. + gets a shake effect).

=====Code Example=====

// We're called by ajax: process input and exit saying what happened
if($_POST) {
$errors = array(); // ...or $input_errors

// Check for errors
if(! somehowCheckValidity($_POST['field_A']))
// "field_A" gets highlighted (red), the text after the | is the
// error message
$errors[] = "field_A|" . gettext("Please specify something valid.");

// Another check, but 2 values (key & cert) need to be highlighted
// on error
if($_POST['cert'] && ! $_POST['key'] ||
$_POST['key'] && ! $_POST['cert']) {
$errors[] = "cert,key|" . gettext("Cert AND key required.");

// There were errors -> print "ERROR" plus a list of error messages;
// then exit
if(count($errors) > 0)
exit("ERROR\n" . implode("\n", $errors));

write_config();
restart_foobar_service()

// Success: print "OKAY", the 2nd line is the save message,
// then exit
exit("OKAY\nSuccessfully saved config and the foobar server has
been restarted ...");

// ... or two lines of save messages (with a link)
// exit("OKAY\nSuccessfully saved config.\n
See <a href='status_filter_reload.php'>status page</a>.");
}
?>

// Sends the form data to the page itself (default) using POST (default)
<form id="myForm" onsubmit="return ajaxFormSubmit('myForm');">
<input type="text" name="field_A" value="...">
<input ...>
</form>

// Sends the form data to the page "/other/page.php" using GET
<form id="otherForm" onsubmit="return ajaxFormSubmit('otherForm', '/other/page.php', 'get');">
<input type="text" name="field_B" value="...">
<input ...>
</form>

// This is also possible:
<form id="form_A" onsubmit="return ajaxFormSubmit('form_B');"> </form>
<form id="form_B" onsubmit="return ajaxFormSubmit('form_A');"> </form>