Aestiva H2O Web Site

Installation:
  Free Downloads
  The H2O Family
  Install Notes

Programming:
  Prerequisites
  H2O Whitepaper
  Online Manual
  Code Examples
  H2O Free Support

What's H2O?
H2O is programming made for the web.

What's it like?
H2O is English-like. If you know some Perl, VB, ASP, or PhP you'll be immediately productive in H2O. It runs on Linux, Mac, Unix, and Windows.

How do I try it?
Download H2O for free. Get it from hosting providers. Or buy on-line.

Where does H2O come from?
The language was invented by Aestiva. H2O stands for:
   HTML with
   HTML/OS
   Overlays.

Chapter 4:
Overlays, Inlays and On-click Overlays
In this chapter you learn the fundamentals of placing Overlays in HTML documents. The title of this chapter refers to the three kinds of Overlays you can use.

You start out by learning how Overlays are written. Then the different ways you can place them in documents and when to use each kind of Overlay, is discussed.

The HTML Document
The HTML document is the center and foundation of Web-based computing. Text, images, sound, video, data stored on the Web server (in files and databases), as well as Javascript, Java Applets and links to other HTML documents are controlled by the HTML document.

In essence, the HTML document is the "control" document of Web pages. In fact, one could say that HTML documents, at least those run in browsers, are the Web.

The Static Web Site
Static Web sites are built from pure HTML documents. These HTML documents are limited since they have no connection to data and files stored on the server.

That's because HTML documents are run on the browser, not the server. Static Web sites do little more than store documents prepared in advance, and then pass them off to users who request them. On static Web sites, the HTML document stored on the server is the same document delivered to the user's browser.

The Dynamic Web Site
Dynamic Web sites have the ability to deliver on-the-fly HTML documents to browsers. Although they must still deliver pure HTML documents to users, the documents stored on the server can contain instructions that reference data and files on the server.

In H2O the special instructions placed in HTML documents are called Overlays.

What Exactly Is An Overlay
These special instructions, or Overlays, are actually program segments. Macros. Specifically, an Overlay is a set of << and >> brackets containing programming code. Overlays can contain calculations, instructions and Overlay Tags. They may contain only a single variable. Or they can contain an instruction or hundreds of instructions.

What's an Overlay Tag
An Overlay tag is a programming function or word used to perform a pre-defined task. As an example, the Overlay <<mynumber=RANDOM(10)>> contains the Overlay tag RANDOM. The tag selects a random number between one and ten and places it in the variable mynumber. Overlay tags are also referred to as Otags, H2O Tags or Reserved Words.

Overlays Containing One or More Instructions
There are two kinds of Overlays. There are Overlays that contain one or more instructions and there are Overlays that contain a single calculation.

Overlays Containing One or More Instructions
The Overlays below are examples of Overlays containing one or more instructions:


<<DISPLAY A /DISPLAY>>	Prints the contents of A.
<<DISPLAY A + B /DISPLAY>>	Prints the result of A + B.
<<A="<font color=red>" B=6 C=7>>	Assigns values to A, B and C.

<<IF A > 5 THEN B=6 /IF C=7>>	Executes a conditional and sets a value for C.

An Overlay can contain as many instructions as you want. Each instruction is separated from the next with one or more spaces or a new line. Like HTML, H2O ignores multiple spaces and new lines and it doesn't care whether a tag is written in upper or lower case. In other words, the three instructions below are the same.


1.	<<DISPLAY A /DISPLAY>>
2.	DiSpLay      a      /DiSpLaY >>
3.	<<
   display
   A 
   /display
   >>

Overlays Containing a Single Calculation
The Overlays below are examples of Overlays containing a single calculation:


<<A>>	Prints the contents of A.
<<A + B>>	Prints the result of A + B.
<<TODAY>>	Prints today's date.

An Overlay with a single calculation is a shorthand way of displaying the results of the same calculation using a DISPLAY instruction. For example, the three Overlays above could also have been written as shown below.


<<DISPLAY A /DISPLAY>>
<<DISPLAY A + B /DISPLAY>>
<<DISPLAY TODAY /DISPLAY>>

Positioning Overlays in a Document
When an HTML document is read by a browser it should begin with a <HTML> tag and end with a </HTML> tag. However the documents stored on the server can begin or end with Overlays.

In H2O, the portion of the document sitting between the <HTML> and </HTML> tags is simply known as the display portion of the document. Outside of this area nothing can be displayed, but programming can be executed.

In general, Overlays can be placed above, inside and below the display portion of the document. You'll see how this works in a moment.

When a Web page is requested, H2O reads the page from top to bottom. If the first thing it finds in a Web page is an Overlay (even before it encounters the <HTML> tag) then it runs it. This kind of Overlay is known as an "Underlay." Underlays can contain any number of instructions.

Underlays can run all the Otags in the H2O arsenal, with one exception - they
can't change the page. Overlays like <<DISPLAY a /DISPLAY>> and <<a>> are not allowed.

This is because Underlays are not connected to any specific location in the page. They're not in the display portion of the page.

When Overlays are placed in the display portion of the page, between the <HTML> and </HTML> tags, they are called "Inlays"

Since Inlays are placed in the display portion of the page they can be used to change the document on-the-fly. Like Underlays, they too can run all of the Otags in the H2O arsenal. But here too there's an exception.

Although Inlays can run tags like DISPLAY, they can't run the GOTO tag. This is because HTML documents are contiguous - a fancy way of saying they must remain whole. Once within the display portion of a page it makes no sense to tell H2O to stop rendering the page and begin over again on some other page.

The third and last kind of Overlay is called the On-click Overlay. These are Overlays placed below the </HTML> tag. They are different than Underlays and Inlays because they're not run as H2O reads a document from top to bottom.

On-click Overlays are run in response to a user clicking a hypertext link or a submit button -- hence the name On-click Overlay. They are also written a bit differently. On-click Overlays are named since they're referenced. They begin with the word Overlay, followed by the name of the On-click Overlay.

An example page with all three kinds of Overlays is shown below. The Overlay at the top of the page is an Underlay. It contains four instructions. The last of the four instructions contains a GOTO tag. The instruction tells H2O to stop reading the page and read home.html instead (in the event tryno is larger than max_tries).

This use of the GOTO tag is appropriate since page rendering has not yet begun.


<< max_tries = 5
   mypass = ""
   IF tryno="ERROR" THEN tryno=1 /IF 
   IF tryno > max_tries THEN GOTO "home.html" /IF
>>
<html>
Try number <<tryno>><br>

Enter Passsword:
<form method=post action=test_password>
<input type=password name=mypass size=10>
<input type=submit value="Go">
</form>
</html>
<<overlay test_password
  IF mypass="LetMeIn" THEN
    GOTO "private.html"
  ELSE
    tryno = tryno + 1
    GOTO PAGE
  /IF
>>

The second Overlay is one that displays the value of the variable tryno. It's an Inlay. It changes the document on-the-fly - printing tryno where it's placed.

Just below the display portion of the page is an On-click Overlay called test_password. It's run when a user clicks Go, the submit button defined in the HTML form on the page.

This is because the ACTION parameter in the HTML form references test_password.
Overlays can also be referenced in hypertext links. For example, suppose you added the following hypertext link to the document:


  <A HREF=test_password NAME=tryme value=0>Clear Counter</a>

The link, when clicked, would set the value of tryme to 0 and run the On-click Overlay test_password. In this case, the instruction tryme = tryme + 1 would run (since mypass
would not be equal to "LetMeIn." When the page was redisplayed it would print a "Try Number 1" on the page.

Some Additional Rules
When using Overlays also keep in mind the following rules.

Overlays can display HTML.
For example, the hypertext link:


<A HREF=done.html NAME=x value=0>Reset Me</a>

is the same as:


<<DISPLAY "<A HREF=done.html NAME=x value=0>Reset Me</a>" /DISPLAY>>

HTML tags can contain Overlays.

For example, you can write:
```
<A HREF=<<PAGE>>>Redisplay</a>
```
The Otag PAGE is a pre-defined tag that contains the name of the current document. Clicking the link above directs the user to the current page.
Overlays cannot contain other Overlays.
For example, you can't write:
```
<< a = a + <<b>> >>
```
Instead, you would write:
```
<<a = a + b>>.
```
Overlay names may not contain a dot.
For example, you can write:
```
<<OVERLAY myprocessing
      instructions here
>>
```
You can't reference the same Overlay if it was written as follows:
```
<<OVERLAY myprocessing.data
      instructions here
>>
```
Overlay tags are optional.
An HTML document does not need to contain Overlays. It can be a standard HTML document, created with any HTML editor, with no programming in it. For example, the page below is valid.
```
<HTML>
Hello World
</HTML>
```
HTML tags are optional.
An HTML document does not need to contain any HTML either. It can be a single
Underlay. For example, the page below is also valid.
```
<< myvariable = "Hello World"
   GOTO "home.html"

>>
```

The last two rules listed above, that Overlays and HTML tags are both optional, means that documents can be either pure HTML documents or they can be pure programming.