Script Library: 1213 scripts
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
 

Documentation for: cgiemailer.r


Usage document for easy CGI examples.

1. Introduction to easy CGI

There is a full suite of scripts that demonstrate how easy it is to code Common Gateway Interface applications in REBOL.

%cgiform.r A simple form handler example.
%cgiformobj.r A simple form handler that includes default values.
%cgiformhtml.r A support script that creates the HTML file for simple form handling
%cgiemailer.r REBOL CGI email
%cgiemailhtml.r The support script that creates the HTML for the emailer
%cgimail.r A very simple web emailer, example
%cgicomment.r A nice simple sequence to allow comments on a web page.
%webcomment.r Creates %article.html for use with %cgicomment.r
%cgidump.r Echo back cgi parameters. Useful for debugging

2. Detailed configuration example

2.1. %cgiemailer.r

This library script shows how REBOL can be used to support web based email, and highlights REBOL flexible and easy Common Gateway Interface scripting.

It requires setup and files placed in an active web server before these scripts are useable.

Some early versions of REBOL do not directly support the newer ESMTP. The internal SEND utility in these older versions of REBOL may fail if your ISP requires Authenicated email transmission.

  • ESMTP -- Extended Simple Mail Transport Protocol

ESMTP is now in widespread use to fight spam. Older versions of REBOL fully support SMTP, but things have changed since mail servers started using the Extended AUTH verb to require password authenication before relaying mail. This is a good thing, and as of March 2007, most platforms have a REBOL release that supports ESMTP.

3. Using %cgiemailer.r along with %cgiemailhtml.r

3.1. Setup %cgiemailer.html with %cgiemailhtml.r

First, the %cgiemailhtml.r needs to be executed on your local system while in a directory that you have permission to write files to. This creates a file %cgiemailer.html that will need to be copied to your active web space.

3.1.1. Assumptions for brevity

For this example we will assume your localhost is a GNU/Linux system running Cheyenne.

  • Cheyenne is in a directory of /home/Cheyenne/.
  • Cheyenne is setup with www-root as www.
  • From your www-root, we will assume a rebol subdirectory.
  • The cgi-bin directory is /home/Cheyenne/www/cgi-bin/
  • And the rebol executable is at /usr/local/bin/rebol
 $ cd         # change directory to your home
 $ rebol -s   # run rebol with security set to ALLOW
 >> write %cgiemailhtml.r read http://www.rebol.org/cgi-bin/cgiwrap/rebol/download-a-script.r?script-name=cgiemailhtml.r
 >> do %cgiemailhtml.r         ; this creates the %cgiemailer.html file
 >> delete %cgiemailhtml.r     ; we don't need this one shot file anymore
 >> q
 

We need to change the output file, to point the HTML form This example uses rpl, for in file replace. You may need to edit the file and then save it. After the edit, the generated file needs to be moved to the web server space.

 $ rpl 'http://ops.rebol.net/cgi-bin/carl/cgiemailer.r' 'http://localhost/cgi-bin/cgiemailer.r' cgiemailer.html
 $ ########## Now lets move it to the web server space
 $ mv -v cgiemailer.html /home/Cheyenne/www/rebol/
 

We can't execute the %cgiemailhtml.r right out of the library, even though will only need to run it once. REBOL will write the output to the directory where the script is executed from. So we make a local copy, do it, then get rid of it

The script that lives in the repository has an action field to find the CGI emailer. It is hard coded to http://ops.rebol.net/cgi-bin/carl/cgiemailer.r we want it to be http://localhost/cgi-bin/cgiemailer.r so we replaced it, in place, with the rpl command. If your GNU/Linux doesn't have rpl installed, just edit the file and make the change.

Then we moved the generated file out of your home directory into the active web server space.

We now have a file, we can access as http://localhost/rebol/cgiemailer.html from a browser.

3.2. Setting up %cgiemailer.r

This is little more straight forward.

 $ rebol -s
 >> write %/home/Cheyenne/www/cgi-bin/cgiemailer.r read http://www.rebol.org/cgi-bin/cgiwrap/rebol/download-a-script.r?script-name=cgiemailer.r
 

Here we read the file out of the library as we wrote it to our cgi-bin directory, in a nice REBOL one liner. There is a little more to that write and read than just getting the file out of the Library. REBOL is line-terminator friendly. Unix, MS-DOS and other operating systems are not. By using the REBOL write native, we don't have to worry about line endings. REBOL knows what's up and will use the correct sequence.

3.2.1. The shebang line

One more thing. CGI scripts need a special header line. This is not a REBOL, but an operating system requirement. Quaintly, this line is called the shebang line. It is a special comment sequence to inform command line shells what executable to use for the following script. The assumptions above have REBOL at /usr/local/bin/rebol

So we need to start the %cgiemailer.r file with

 #!/usr/local/bin/rebol -cswq
 

We could edit the file, or use rpl again

 $ rpl -e 'REBOL [' '#!/usr/local/bin/rebol -cswq\n\nREBOL [' /home/Cheyenne/www/cgi-bin/cgiemailer.r
 

If you need to use an editor, what the line above does is insert the shebang line to the top of the file and add a newline spacer.

3.3. Running %cgiemailer.r

We just need to start up a browser and point it our cgiemailer.html

 $ rebol
 >> browse http://localhost/rebol/cgiemailer.html
 

3.4. Other configuration

The other scripts in the suite, follow very similar configuration.

These scripts are examples. All need some form of local customization to be used. Treat these scripts as starting points as you build your technical empire.

3.4.1. Things to watch for

  • shebang lines point to the REBOL executable
  • HTML ACTION= lines point to the corrent CGI script
  • Watch for hardcoded email addresses (%cgimail.r)
  • Things like %article.html needs a local edit so it makes sense on your site

3.5. Executing right from the Library

These scripts are of no use when executed directly out of the library.

All of them require some form of local configuration changes.

3.6. What you can learn

3.6.1. REBOL is great at CGI

REBOL CGI solutions can be short, sweet and easy. REBOL CGI solutions can be complex, creative, complete. rebol.org being a shining example.

3.6.2. Keep web servers happy

Begin a CGI script by printing the http Content-Type header line

 print "Content-Type: text/plain^/"  ;-- Required Page Header
 

This will help keep your web server from timing out or stray output causing problems.

3.6.3. Other trickery

You can also send other http responses. You can use something like

 #!/local/bin/rebol -cswq

 REBOL [
     Title: "Not built yet - redirect"
 ]

 ; start html browser output
 print "location: /sorry.html^/content-type: text/html^/"
 
to get quick redirects and less dead links as you build up sites.

3.6.4. Use %cgidump.r for development

The %cgidump.r can be used to display parameters coming out of an HTML form.

4. Credits

  • %cgiemailer.r and %cgiemailhtml.r Original author: Unknown, probably RT, probably Carl.
  • %cgiform.r, %cgiformobj.r and cgiformhtml.r Original author: Unknown
  • %cgimail.r Original author: Unknown
  • %cgicomment.r and %webcomment.r Original author: Unknown
  • %cgidump.r Original author: Unknown
  • The rebol.org Library Team
  • Usage document by Brian Tiffin, Library Team Apprentice, Last updated: 28-Apr-2007