Aptilis manual: How to do Web Forms

How to do Web Forms		Topics

1. Introduction
2. How it happens
3. Form Fields
4. Calling an Aptilis script from a form
5. Replying to a form
6. The magic line

1. Introduction
Aptilis is a godsend (no, really) for the handling of Web forms.
Although aptilis follows the CGI model, you don't have to worry about the nitty gritty details!
This is a typical form (that does nothing):

Form Example:
Your email address: Your comments:

Now the smart part is for you to write a programme which we will call a 'script' (for historical reasons).
This programme will be sent the content of the form in a certain way so that you can do something with it. Fortunately, Aptilis makes it incredibly easy for you to do such scripts.

2. How It Happens
Client-Server diagram

The user requests a page, that happens to contain a form.
The server sends the page.
The user fills the form and clicks the submit button: the client sends the form and its collected data.
The sever runs the script and sends the output of the script to the user.
The user is happy. In most cases.

3. Form Fields
In the example above, the fields are the two boxes where you can enter your e-mail address and some comments.
If you go into the source of a form, you will notice that all fields have something in common: They have a name. This name is very important as you will use it to get the value of the different fields.
Now, one of the really nice tricks Aptilis has got up its sleeve is that you needn't write a single line of programme to retrieve the value of the fields: they have been stored in variables for you!!
Example:
If in your form, you have the following field:

<INPUT type="text" name="email" size=20>

all you need to do to, say, print the e-mail address given, is:

sub main

  // first a little magic line!!
  print("Content-type: text/html\n\n")

  print(email$)

end sub

Note that you shall not use dollar signs in field names, that is in the HTML part.

4. Calling an Aptilis script from a form
Calling an aptilis script form a form is simple, all you need to do is follow this guide:

Create the form
For example with the Notepad or any other text utility you're used to.
call the aptilis interpreter
You do that in the FORM tag of your form:
```
<FORM method="http://www.myserver.com/cgi-bin/aptilis.exe" method="POST">
```
Of course, you have to adapt the example given to suit your needs.
You can also use the GET method, but POST is safer.
If you do not know the path information for your server, ask you system admin.
Indicate which script to use
Just after the FORM tag, add the following line:
```
<INPUT type="hidden" name="file" value="myscript.e.txt">
```
But replace 'myscript.e.txt' with the relevant value, for example:
NT/Win95 server: c:\webshare\aptilis-scripts\poll.e.txt
Unix server: /home/httpd/aptilis-scripts/poll.e.txt
for a script called 'poll.e.txt'. As you have noted, the full path is needed in any case.
If you do not know the path information for your server, ask your system admin. You can also find it when you use your FTP programme to upload files to your script directory
Write the script
...and put it exactly where you said you would in the hidden 'file' field of your HTML form.

Note to Unix Users.
Making the script 'Executable' allows you to call the script directly into the 'action' parameter of the <FORM...> tag. In this case you don't need the hidden 'file' field, provided your system understands another magic line convention: '#!path_to_interpreter'. If you know what I'm talking about, you know where to put it.

5. Replying to a form
Your script will be called when the user clicks the 'submit' button. The script will be run on the server, NOT on the user's machine.
After the submit button has been clicked, the user's HTML is cleared. It is now up to you to re-create a new Web page for the user.
How do you do that?
Simple! You just use the print predefined sub to do the page:

sub main

  // Magic line
  print("Content-type: text/html\n\n")

  print("<HTML><BODY>\n")
  print("Hello World!!\n")
  print("</BODY></HTML>")

end sub

and that's all!! Of course, this was the 'Basics'. It's up to you to use the databse, direct mail (sendmail), and mathematic functions, etc... to do something a bit more useful!

6. The magic line
You have already entcountered the magic line in such code fragments:

  // Magic line
  print("Content-type: text/html\n\n")

(The first line starting with '//' is just a comment and does nothing)
The magic line is absolutely necessary and its role is to tell the browser (Netscape, Mosaic, Internet Explorer, etc...) what is going to be sent to it. Other magic lines are:

  // the text will contain no HTML tags
  print("Content-type: text/plain\n\n")

  // A picture will be returned.
  print("Content-type: image/gif\n\n")

The different types are called 'MIME' types and, That's a tip you can view some of them in Netscape, if you select the 'Options' menu, then choose 'General preferences' and finally click the 'Helpers' thumbnail.
Note that all our magic lines end with two '\n', which mean 'two carriage return', and that's also absolutely necessary for the browser to know when to start to display something.
Another tip: The magic line is actually part of the header, which can contain several other things, like a frame target for a frame-enabled browser (which worked only for Netscape until Version 4.x):

  print("target: second_window\n")
  print("Content-type: text/plain\n\n")