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:

page name

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>

mv_action

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:

back

Goes to the page in mv_nextpage. No user variable update.

cancel

All user information is erased, and the shopping cart is emptied. The user is then sent to mv_nextpage.

refresh

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).

return

Updates the user variables and returns to the page defined in mv_nextpage.

search

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).

submit

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.