8.2. Form Actions
Interchange form processing is based on an action and a todo. This can be gated with mv_form_profile to determine actions and form values based on a check for required values or other preconditions.
The predefined actions at the first level are:
process process a todo search form-based search scan path-based search order order an item
Any action can be defined with ActionMap.
The process action has a second todo level called with mv_todo or mv_doit. The mv_todo takes preference over mv_doit, which can be used to set a default if no mv_todo is set.
The action can be specified with any of:
Calling the page "search" will cause the search action. process will cause a form process action, etc. Examples:
<FORM ACTION="/cgi-bin/simple/search" METHOD=POST> <INPUT NAME=mv_searchspec> </FORM>
The above is a complete search in Interchange. It causes a simple text search of the default products database(s). Normally hard-coded paths are not used, but a Interchange tag can be used to specify it for portability:
<FORM ACTION="[area search]" METHOD=POST> <INPUT NAME=mv_searchspec> </FORM>
The tag [process] is often seen in Interchange forms. The above can be called equivalently with:
<FORM ACTION="[process]" METHOD=POST> <INPUT TYPE=hidden NAME=mv_todo VALUE=search> <INPUT NAME=mv_searchspec> </FORM>
Setting the special variable mv_action causes the page name to be ignored as the action source. The above forms can use this as a synonym:
<FORM ACTION="[area foo]" METHOD=post> <INPUT TYPE=hidden NAME=mv_action VALUE=search> <INPUT NAME=mv_searchspec> </FORM>
The page name will be used to set mv_nextpage, if it is not otherwise defined. If mv_nextpage is present in the form, it will be ignored.
The second level todo for the process action has these defined by default:
back Go to mv_nextpage, don't update variables search Trigger a search submit Submit a form for validation (and possibly a final order) go Go to mv_nextpage (same as return) return Go to mv_nextpage, update variables set Update a database table refresh Go to mv_orderpage|mv_nextpage and check for ordered items cancel Erase the user session
If a page name is defined as an action with ActionMap or use of Interchange's predefined action process, it will cause form processing. First level is setting the special page name process, or mv_action set to do a form process, the Interchange form can be used for any number of actions. The actions are mapped by the ActionMap directive in the catalog configuration file, and are selected on the form with either the mv_todo or mv_doit variables.
To set a default action for a process form, set the variable mv_doit as a hidden variable:
<INPUT TYPE=hidden NAME=mv_doit VALUE=refresh>
When the mv_todo value is not found, the refresh action defined in mv_doit will be used instead.
More on the defined actions:
Goes to the page in mv_nextpage. No user variable update.
All user information is erased, and the shopping cart is emptied. The user is then sent to mv_nextpage.
Checks for newly-ordered items in mv_order_item, looking for on-the-fly items if that is defined, then updates the shopping cart with any changed quantities or options. Finally updates the user variables and returns to the page defined in mv_orderpage or mv_nextpage (in that order of preference).
Updates the user variables and returns to the page defined in mv_nextpage.
The shopping cart and user variables are updated, then the form variables are interpreted and the search specification contained therein is dispatched to the search engine. Results are returned on the defined search page (set by mv_search_page or the search page directives).
Submits the form for order processing. If no order profile is defined with the mv_order_profile variable, the order is checked to see if the current cart contains any items and the order is submitted.
If there is an order profile defined, the form will be checked against the definition in the order profile and submitted if the pragma &final is set to yes. If &final is set to no (the default) and the check succeeds, the user will be routed to the Interchange page defined in mv_successpage or mv_nextpage. If the check fails, the user will be routed to mv_failpage or mv_nextpage in that order.