;;; sec6.01.mhtml: -*- Meta-HTML -*- 

;;;  Copyright (c) 1996 Universal Access Inc.
;;;  Author: Henry Minsky (hqm@ua.com) Sun Sep 15 11:06:05 1996.
<set-var title="Handling Posted Data And Forms">
<include header.mhtml>

<plain-text>
  <pagelist-control-panel>
  <H2>Handling  HTML Forms</h2>

  It is easy to create fill-out forms using HTML. For example, suppose we want
  a form which can be used to order some food from a Chinese restaurant:
</plain-text>

<example-table result>
<form method=post>
  Appetizer:  <select>
    <option>Peking Ravioli
    <option>Egg Rolls
    <option>Fried Wontons
  </select>

  How many? <input type=text size=4 name=quantity>

  <input type=submit value="Place Order">
</form>
</example-table>

<plain-text>
  Now, we have created a form, but how do we handle it after
  the user has filled it out and submitted it? We might want 
  to save the results to a file, send an email message, or add
  an entry to a database.


  Before <meta-html>, the only way to do these things was to use a CGI
  script program. Now, however, there is a much easier way. Using
  <meta-html> , we can handle the posted form data directly with our web
  pages.

  <h3> All HTML Forms <i>must</i> Specify A Handler URL</h3> 

  No matter what method we are using to handle the form, we must specify
  a <em>URL</em> location which tells the browser where to send the data
  from the form when it is submitted. We use the <code>action</code>
  attribute of the HTML <code>form</code> tag to specify the URL of the
  form handler.

  In this example, we will make the action of the form be the same page
  you are now reading, using the <meta-html> variable <varref mhtml::location>.
</plain-text>

<example-table result>
<form action="<get-var mhtml::location>" method=POST>
  Appetizer:  <select name=kind-of-food>
    <option>Peking Ravioli
    <option>Egg Rolls
    <option>Fried Wontons
  </select>

  How many? <input type=text size=4 name=quantity>

  <input type=submit value="Place Order">
</form>
</example-table>

<plain-text>
  When the user clicks on the "Place Order" button, the contents of the
  form, i.e., the input field values which the user has selected, will
  be posted to the web server at the target URL indicated in the
  <code>action</code> attribute of the form.

  Now here is the good part. When a page on the web server running
  <meta-html> is selected as the target of a form, all of the form input
  field data magically appears in a special package named
  </code>POSTED</code>.

  For example, fill out the form above and click on the "Place Order"
  button. The form specifies that this page you are now reading is
  the target action of the form. You will see the values which you filled
  out appear in the listing of the POSTED package. For each input
  field in your form, a variable appears in the POSTED package, whose
  name is the name of the input field, and whose value is the
  value which was entered by the user for that input.

  <include /macros/dump-package.mhtml>
  <dump-package posted>

  <h3>Form Field Values Also Appear in the DEFAULT Package</h3>

  As a special convenience, the variables corresponding to the form
  fields also are put into the DEFAULT package, so that you can reference
  them without needing to prefix them with <code>POSTED::</code>.
</plain-text>

<example-table result>
<when <and
       <get-var quantity>
       <get-var kind-of-food>>>
  You ordered <get-var quantity> of <get-var kind-of-food>.
</when>
</example-table>

<pagelist-control-panel>
<include footer.mhtml>
