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

;;;  Copyright (c) 1996 Universal Access Inc.
;;;  Author: Henry Minsky (hqm@ua.com) Sun Sep 15 11:05:17 1996.
<set-var title="Control Flow">
<include header.mhtml>

<plain-text>
  <h2>Control Flow</h2>

  In a basic <meta-html> document, everything in the page will
  be executed, in order, from start to finish. This is commonly
  what you want, but in many cases it is desirable to control
  how or if certain sections of your page are executed.

  The basic flow of control functions are <funref if>, <funref when>,
  <funref while>, <funref ifeq> and <funref redirect>.

  <funref if>, <funref when>, and <funref while> are called
  <em>conditionals</em> because they conditionally execute some code,
  based on some value which you supply. Let's look at the <funref when>
  statement first.

  The syntax of a when statement is:

  <pre>
  &lt;when TEST&gt;
  <i>body</i>
  &lt;/when&gt;
  </pre>

  <funref when> takes as an argument a TEST value, which is called a
  predicate, and if that value is not an empty-string, (also known
  as a <em>non-null</em> value), then the code within the <em>body</em>
  of the <code>when</code> is evaluated. Otherwise the body of the
  <code>when</code> is ignored.

  The complete list of relational operators is covered in the
  <meta-html> reference manual at <secref Relational Operators>, <secref
								  Arithmetic Operators> and <secref Logical Operators>.

  Let's say that you want to have a certain section of HTML on your page
  only be sent to the browser when it is a holiday. We will assume that
  there is a variable called <code>holiday</code> which is set to some
  non-null value if it is a holiday today.

  <example-table>
  <h2>Welcome to Foo Corporation's Home Page!</h2>
  <p>
  <when <get-var holiday>>
    <center>It's a holiday! Go home! We're closed!</center>
    Remember, Foo Corporation is closed on all holidays.
    <p>
    Thank you, <br>
    The Management
  </when>
  </example-table>

  Now, if the variable <code>holiday</code> is set to any non-null value,
  the message above will be printed:

  <example-table result>
  <set-var holiday=true>
  <h2>Welcome to Foo Corporation's Home Page!</h2>
  <p>
  <when <get-var holiday>>
    <center>It's a holiday! Go home! We're closed!</center>
    Remember, Foo Corporation is closed on all holidays.
    <p>
    Thank you, <br>
    The Management
  </when>
  </example-table>

  <h3> Use of the <funref not> operator in conditionals </h3>

  By using the <funref not> operator, you can make a test
  for the absence of a variable value, as well as its presence.
  In this next case, the variable <i>holiday</i> is set to the
  empty string. Thus, the expression
  <verbatim quote><not <get-var holiday>></verbatim>
  evaluates to <i>true</i>, and the second when clause is the
  one which is used.

  <example-table result>
  <set-var holiday="">
  <h2>Welcome to Foo Corporation's Home Page!</h2>
  <p>
  <when <get-var holiday>>
    <center>It's a holiday! Go home! We're closed!</center>
    Remember, Foo Corporation is closed on all holidays.
  </when>
  <when <not <get-var holiday>>>
    Stop surfing the web and get back to work.
  </when>
  <p>
  Thank you, <br>
  The Management
  </example-table>


  <h2>The <funref if> statement</h2>

  The <funref if> statement is a more general statement than
  <funref when> because it allows you to specify an alternate
  action to take if the predicate you pass is false.

  <pre>
  &lt;if TEST              <i>predicate</i>
      IF-TRUE-DO-THIS   <i>consequent (or <b>then</b>) clause</i>
    ELSE-DO-THIS&gt;       <i>alternative (or <b>else</b>) clause</i>
  </pre>

  Here is a simple example of an <funref if> statement

</plain-text>
<example-table result>
<set-var foo=10>

<if <gt foo 5>
    "Foo is greater than 5"
  "Foo is not greater than 5">
</example-table>
<plain-text>
  Now if we set <code>foo</code> to 3, the predicate will 
  be false, so we will get the else clause of the if statement.

</plain-text>

<example-table result>
<set-var foo=3>

<if <gt foo 5>
    "Foo is greater than 5"
  "Foo is not greater than 5">
</example-table>
<plain-text>

  You can also omit the <i>else</i> clause, which gives you the same 
  behavior as the <funref when> clause, but using the syntax of 
  the simple <i>if</i> tag:

</plain-text>
<example-table result>
<if <eq foo 5>
    "Foo is equal to 5">
</example-table>
<plain-text>

  <h2>The <funref prog> Block Statement</h2>

  The <funref prog> statement lets you group together a list of
  statements or source text into a single block. 

  The <funref if> statement expects a single expression for its
  <em>then</em> clause and <em>else</em> clause. If you want to have
  multiple expressions in the <em>then</em> or <em>else</em> clauses,
  you must group the expressions together into a single block using
  a <funref prog> statement.

</plain-text>
<example-table result>
<set-var foo=6>

<if <gt foo 5>
    <prog
      <center>
      <h2> Well, it looks like foo is greater than 5.</h2>
      </center>
      I think that is really exciting, don't you.
      <p>
      I mean, it's not every day that foo gets this large, is it?
      >
  >    
</example-table>
<plain-text>

<h2> The <funref while> Statement</h2>

You can perform iteration using the <funref while> statement. 
The syntax of <code>while</code> is

<pre>
&lt;while TEST&gt;
  <i>body</i>
 &lt;/while&gt;
</pre>

The <i>body</i> of the <funref while> will be executed repeatedly
until the TEST is becomes null. There is a built in mechanism in
<meta-html> to prevent runaway looping. The variable <varref
mhtml::iteration-limit> sets the maximum number of times a loop will
run.

Here is an example of a loop using <funref while>

</plain-text>
<example-table result>
<set-var lines=0>


<while <lt lines 10>>
  This is line number <get-var lines>
  <br>
  <set-var lines=<add lines 1>>
</while>

</example-table>
<p>
Of course, any HTML or Meta-HTML code can be in the 
body of a while loop.
<p>

<example-table result>
<set-var bears=0>

<while <lt bears 4>>
   This is bear number <get-var bears>
  <img src="<get-var mhtml::url-to-top>/images/bear.gif" align=middle>
  <br>
  <increment bears>
</while>

</example-table>
<plain-text>

<h2>Nested WHILE Loops</h2>

<funref while> loops can be nested. For example, a two-dimensional
table could be created as follows:

<p>
</plain-text>
<example-table result>
<set-var rows=0 columns=0>

<table border=1>
<while <lt rows 4>>
  <tr>
    <set-var columns=0>
    <while <lt columns 4>>
      <th> Row <get-var rows>, Col <get-var columns></th>
      <increment columns>
    </while>
  </tr>
  <increment rows>
</while>
</table>
</example-table>
<plain-text>

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