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

;;;  Copyright (c) 1996 Universal Access Inc.
;;;  Author: Henry Minsky (hqm@ua.com) Sun Sep 15 11:06:28 1996.
<set-var title="Using Sessions, Continued">
<include header.mhtml>

<plain-text>
  <pagelist-control-panel>
  <h2>Using Sessions, Continued</h2>

  Now we are browsing a new page, but if you entered your personal
  information into the form on the previous page, then you will see 
  that information referenced below:
</plain-text>

<example-table result>
<FONT SIZE=+1>
<when <get-session-var firstname>>
  Hello, <get-session-var firstname>. 
</when>

<when <get-session-var favorite-color>>
  I hear your favorite color is <FONT COLOR=<get-session-var favorite-color>>
  <get-session-var favorite-color></FONT>.
</when>
</FONT>
</example-table>

<plain-text>
  How did this work? It worked because on this Web site there is a
  <i>session</i> which is associated with every browser.

  The <a href="/meta-html/manual">online reference manual</a> lists all
  the <meta-html> functions which involve sessions in the <secref
							   Sessions> section.

  A session is initiated by calling <funref require-session> someplace
  in your web page.  <funref require-session> is a command which does a
  lot of work for you, and thus has a lot of options. You will want to
  specify how long a session is valid for, and what to do if no session
  currently exists.

  Below is an example of a very basic call to <funref require-session>,
  which is similar to the code actually being used for the pages of this
  Web site:

  <example-table>
  <require-session
   missing = <prog
	       <set-var site::new-arrival=true>
	       <set-var anonymous=anonymous>
	       <create-session anonymous allow-multiple>
	       <set-session-timeout 60>>>
  </example-table>

  The example above checks for an existing session, and if one does not
  exist, it creates a one whose name is "anonymous". Multiple users can
  be connected to the Web server, and all can have their own unique
  anonymous sessions. 

  Once a session has been created, you can use the <funref set-session-var>
  and <funref get-session-var> functions to write and read persistent
  data to the session. The session will follow the browser anyplace it
  goes on the site.

  <h2> Exporting and Importing Package Data from a Session</h2> 

  <funref get-session-var> and <funref set-session-var> are good for
  saving and restoring single variables which contain session state
  information, but sometimes you will want to save and restore larger
  chunks of data.

  <funref session-import> and <funref session-export> can be used to
  save and restore entire <secref Packages> from a session.

  An example of where this is might be useful is in handling fill-out forms.
  When an HTML form is submitted to your server, all the data in the
  various fields are automatically entered into the POSTED package, where
  you can access them using <funref get-var>.

  Let's say that we have the following fill-out form.
</plain-text>

<example-table result>
<FORM ACTION=<thisdoc>#SECTION-2 METHOD=POST>
  <H2>Internet Pizza Delivery Service</h2>
  Type in your street address: <INPUT NAME="address"> <BR>
  Type in your phone number: <INPUT NAME="phone"> <BR>
  Which toppings would you like? <BR>
  <OL>
    <LI> <INPUT TYPE="checkbox" NAME="topping" VALUE="Mushrooms (mmmm)">
    Mushrooms.
    <LI> <INPUT TYPE="checkbox" NAME="topping" VALUE="peppers"> Peppers.
    <LI> <INPUT TYPE="checkbox" NAME="topping" VALUE="anchovies (YUCK!)">
    Anchovies.
  </OL>
  To order your pizza, press this button:
  <INPUT TYPE="submit"VALUE="Order Pizza">
</FORM>
</example-table>

<plain-text>
  <a name="SECTION-2">
    All of the data in the form above will appear in the <meta-html>
    POSTED package of the form's target page. Fill out the form
    above and press "Order Pizza".

    <blockquote>
    The <i>dump-package</i> utility is used below to list
    the contents of a package into the current page. <i>dump-package</i>
    is a very useful debugging tool, which can be used anyplace inside
    your <meta-htmL> pages.
    </blockquote>
  </plain-text>

  <example-table result>
  <include /macros/dump-package.mhtml>
  <dump-package posted>
  </example-table>

  <plain-text>
    You can save out the entire contents of the POSTED package to your
    current session, using the <funref session-export> function. In this
    example, we save out every variable in the POSTED package into a new
    package called USER-INFO, which is stored in the current session.

    <example-table>
    <session-export POSTED USER-INFO>
    </example-table>
    <session-export POSTED USER-INFO>

    Once you have saved out a package, you can restore it at any time,
    while the session is active, using <funref session-import>

    <example-table result>
    <session-import USER-INFO USER-INFO>
    <dump-package USER-INFO>
    </example-table>

    If we did not explicitly specify the package into which the
    session package should be loaded, the symbols would be loaded into
    the current package (usually DEFAULT).

    <h2> Using Session Information in Forms</h2>

    Now, using our session data, let's fill in some default values for the
    form input fields. Since we have saved all the data which the user
    provided into our session, we can retrieve that data and use
    it to provide default input values in the form.
  </plain-text>

  <example-table result>
  <FORM ACTION=<thisdoc>#SECTION-3 METHOD=POST>
    <H2>Internet Pizza Delivery Service</h2>
    Type in your street address:
    <INPUT NAME="address" 
	   VALUE=<get-var user-info::address>> <BR>
    Type in your phone number: 
    <INPUT NAME="phone"
	   VALUE=<get-var user-info::phone>> <BR>
    Which toppings would you like? <BR>
    <OL>
      <LI> <INPUT TYPE="checkbox" NAME="topping" VALUE="Mushrooms (mmmm)">
      Mushrooms.
      <LI> <INPUT TYPE="checkbox" NAME="topping" VALUE="peppers"> Peppers.
      <LI> <INPUT TYPE="checkbox" NAME="topping" VALUE="anchovies (YUCK!)">
      Anchovies.
    </OL>
    To order your pizza, press this button:
    <INPUT TYPE="submit"VALUE="Order Pizza">
  </FORM>
  </example-table>

  <a name="SECTION-3"> 
    <plain-text>
      Notice that the <b>previous</b> values which you
      filled out in the first form are now retrieved and displayed in this
      form.

      <pagelist-control-panel>
    </plain-text>
    <include footer.mhtml>
