Displaying the Results of your Form Submission
(or, Not Redirecting Users After Submitting a Form in Drupal 5)
With almost every form submission, you want to offer some feedback to the user. A lot of the time this can be a simple message suitable for a drupal_set_message() call (like 'Your message has been sent' or 'Your data has been stored' or simply 'Form submission successful'), but sometimes the entire point of the form is to generate a more complex result. In these cases you probably want the result to be the focus of the page, rather than a note at the top of something else.
One option is to create a processing page and forward the values from your successfully submitted form here. This may be suitable if you have a small set of inputs (for example, a search form that forwards the input 'foo' to the URL 'search/node/foo', or something more elaborate like 'myform/results?x=foo&y=bar&z=wang') but may become more unwieldy if many form elements are involved. This could be tackled by saving the results to a session variable - or even a database table - and then calling a simple URL that retrieves the stored data (eg 'myform/results', or 'myform/results/n' where n is the unique identifier of the stored database row). However, this might not be ideal if you're dealing with short-lived or sensitive data.
A much more elegant solution is to have the results displayed by the form itself. This can be achieved quite easily by (ab)using the multi-step forms approach - essentially creating a two-step form, the second page of which exists purely to display data (through a form element of #type 'markup') and has no submit button. Moreover, since it's just two steps, you can do away with the 'step' variable and test for the presence of $form_values directly.
<?php
/**
*Form assembly function
*/
function myform($form_values = null) {
$form = array(
'#redirect' => false, // stops the form redirecting to itself after validation
'#multistep' => true, // Passes the form values back through as $form_values
);
if (!isset($form_values)) {
// Fresh form - add elements to $form array here
$form['submit'] = array( '#value' => t('Submit'), '#type' => 'submit');
}
else {
// Form has been submitted - display results instead of form.
$markup = '';
// PROCESS results, store in $markup
$form['result'] = array( '#value' => $markup, '#type' => 'markup' );
}
return $form;
}
?>No _submit function is required, though one may be added if there is some special processing or storage to be triggered in addition to the display. (Note that the form's #redirect value is used in preference to the _submit function's returned path. For more on user redirection, see Redirecting Users After Submitting a Form in Drupal 5 - but if you wanted to redirect your user, why are you reading this article?)
The finished form can then be displayed by creating a drupal_get_form menu callback as normal:
<?php
/**
*Implementation of hook_menu
*/
function mymodule_menu($may_cache) {
$items = array();
if ($may_cache) {
$items[] = array(
'path' => 'myform',
'access' => true,
'callback' => 'drupal_get_form',
'callback arguments' => 'myform',
'title' => t('My form'),
);
}
return $items;
}
?>-- Developed from code originally created in discussion of #324243: Optional results page step in the form API.