Custom (Form) destination provides a way to define where a form should redirect the user upon submission.
When you submit a form, Drupal deals with your input (saving your node, sending an email, storing a setting, etc..) and then redirect you to a page. You usually are sent back to the page originating the request (for example when you enable a module) or to a different page (for example after you succesfully submit a new node, it will be displayed to you).
There may be some cases in which you want to override the default behaviour, that is you want to be redirected to a different page (see the Examples section below).
This is where Custom (Form) destination comes in handy, giving you the ability to define the page a form redirects to upon submission.
Ok. How do I use it?
To set a new destination page for a form you need 2 things (drumrolls): a destination page and a form.
A destination page is any valid Drupal path. Examples are "node/58", "mylandingpage", "admin/settings". Anything after ?q= or, if Clean URLs are enabled, anything after your Drupal root in the URL (e.g.: http://www.example.org/blog/2008/07 or, for sub-dir installations, http://www.example.org/sub/dir/drupal/blog/2008/07).
You will also need to identify the form finding out what we call a Form ID. It can be easily found by viewing the source of the page containing the form and navigating to find out the field with name "form_id". The value of the value= attribute of that field is the Form ID you are looking for.
If source code is not your thing you can install form inspect module, which will reveal the Form ID for you.
Once you have collected these two important info, you can navigate to Administer › Site configuration › Custom destination, click on the "Add custom destination" tab and input them in the corresponding field, hit the button and test that everything works!
Core contact.module redirects to "node/". You can use Custom destination to override this behaviour: using its simple interface define a new destination (any valid Drupal path) for the "Form ID" 'contact_mail_page' and you are all set!
Future possible improvements (feedback is welcome)
- print a notice on forms affected by the module current module configuration
- integration with Token module
Developer (mostly notes to myself)
- add some AHAH juice
- include tests
Development of this module has been kindly sponsored by John_Kenney.
Thanks to dipen Dojo wiki article from which I borrowed help text about Form ID.
Thanks to the core Path module from which I took a "great bit" of inspiration and code.