User Guide

This guide assumes the reader is already familiar with HTML forms. If you have not already done so, please carefully read the following document:

NCSA's fill-out form guide

When you have created a form or two yourself, you are ready to go ahead and learn to program in BRL.

• Basic BRL templates
• CGI environment variables
• HTML encoding
• Sending e-mail
  • PGP Encryption
  • MIME Encoding

Basic BRL templates

Suppose you had a WWW form that let users enter their names and e-mail addresses, and you wanted to present this information to the user to check accuracy before continuing. This requires dynamically generating a web page with that info. You would create a page that looks just like this:

Please verify

• Your name: [name]
• Your e-mail address: [address]

Suppose this BRL template page was at at the following URL:

http://example.com/verification.html
\                /\                /
 `--- Part 1 ---'  `--- Part 2 ---'

Split the resulting URL into two parts as shown, and insert the script name (check with your webmaster, but it's usually /fcgi-bin/brlfcgi).

http://example.com/fcgi-bin/brlfcgi/verification.html
\                /\               /\                /
 `--- Part 1 ---'  `-script name-'  `--- Part 2 ---'

This is the URL to use as the ACTION of your form. For simplicity, you may leave out part 1, but you must include it if you want to test your form as a local file. If you don't know what that means, just feel free to omit part 1.

BRL templates are just HTML pages. Square brackets denote expressions, which are instructions for inserting dynamically-generated HTML. The most basic expressions are just variables which correspond to form inputs or to CGI environment variables.

CGI environment variables

CGI environment variables can be included much like form inputs:

Please verify

• Your name: [name]
• Your e-mail address: [address]
• Your browser: [HTTP_USER_AGENT]

Note that neither kind of variable is case-sensitive, but it is good style to use lower case for inputs and upper case for environment variables. A form input with the same name as an environment variable normally takes precedence, but you can use getenv for sensitive environment variables like REMOTE_USER to make sure you're not being spoofed.

• Your identity: [(getenv REMOTE_USER)]

HTML encoding

Continuing with the previous example, suppose you had problems with people typing e-mail addresses with angle brackets, e.g. <santa@northpole.org>. Because angle brackets have special meaning in HTML, the e-mail address does not show up. The angle brackets need to be encoded as &lt; and &gt;. Here is how you would do it:

• Your name: [name]
• Your e-mail address: [(html address)]

Sending e-mail

A special function called html-mail will read text in the next HTML tag (usually PRE) and send an e-mail message according to its contents. Here is an example.

[(html-mail)]
<pre>
From: support@example.com
To: [email]
Subject: your answers

Address....[address]
Name.......[name]
</pre>

Normally the resulting message is also displayed on the dynamically-generated page, but this can be changed with the silent function:

[(silent (html-mail))]
<pre>
From: support@example.com
...

PGP Encryption

If you are sending sensitive information such as credit-card numbers through e-mail, you should encrypt it using PGP. Arrange with your webmaster for the appropriate public key to be accessible to the web server, then put the following in a BRL page to encrypt an input named ccard with the PGP public key for <billing@example.com>.

[(brl-pgp-encrypt "billing@example.com" ccard)]

MIME Encoding

Accented characters tend to get stripped out of mail messages. If you have people sending putting characters in WWW forms and receive mail with a MIME-capable mail reader, you can do something like this:

[(html-mail)]
<pre>
From: support@example.com
To: [email]
Subject: your comments
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset="iso-8859-1"

[(brl-qp-encode comments)]
</pre>

Note: As of BRL 1.4, only quoted-printable encoding is available. Later releases of BRL may have more general MIME encoding.

Using the Database

SQL, the Standard Query Language is the standard way to communicate with a database. BRL will execute arbitrary SQL statements and return either a table of the results (SELECT) or the number of rows processed (INSERT, UPDATE, DELETE).

SELECT