SubscribeThe Common Gateway Interface, or CGI, remains a valid and simple way to create dynamic web pages and services. MiniScript is an excellent choice for creating CGI scripts. In this post, we'll go over how to set up your web environment and get started making your own CGI scripts, along with some simple examples.
What is CGI?
As noted above, CGI stands for Common Gateway Interface. It's a standard way for a web server (such as Apache) to interface with an external program (such as a script you have written). Because CGI is a standard, it can work with any web server, and any external program written in any language — as long as it understands CGI.
CGI is simple: when the web server gets a web page request that ends in .cgi (or some other file extension configured to run via CGI), instead of just reading that file and returning the result to the web browser, it actually executes that file, after setting a bunch of environment variables with data about the request. The program run is responsible for generating the response, typically (though not necessarily) a page of HTML. The program can generate unique output based on the request parameters, the contents of any files it can read, random numbers, or whatever, thus replacing static, immutable web pages with dynamic content.
In the old days, CGI programs were typically written as BASH or Perl scripts. In somewhat more recent years, Python has been a popular choice. But now you can write CGI programs in MiniScript, applying all the advantages of the language you love to web development.
Configuration
You will of course need access to a web server, with at least one directory you can add/edit files in.
Then you'll need to tell it to process certain files as CGI. How exactly you do that varies depending on what web server software you're using. Most web sites use Apache, and in that case you can enable CGI processing on a per-directory basis using a .htaccess file. Just create a file in your directory called exactly .htaccess (including the dot), and paste in:
AddHandler cgi-script .cgi .ms Options +ExecCGI
The first line tells Apache that any file ending in .cgi or .ms should be treated as a CGI program. The second line tells Apache that CGI programs are permitted in this directory at all. (See here for more detail if needed.)
You will also need to be sure command-line MiniScript is installed in your system. If you have full control over the web server, the standard place to put it is in /usr/local/bin. If not, you can put it anywhere, and adjust your script files accordingly.
Your First Script
Once that's done, you're ready to start coding! Create another file in the same directory. You can call ithello.cgi or hello.ms — either will work, though I slightly prefer hello.ms since it proudly declares (or at least mildly hints) that you're using MiniScript! In either case, the content should look like:
print "Content-Type: text/html" print print "Hello world!"
Like any command-line script, the first line starts with a shebang (#!) and the path to the actual executable. If you've installed MiniScript somewhere other than /usr/local/bin, change this line to the correct path.
The rest of the file is plain old MiniScript code! However, it must first start by printing HTTP headers, at least Content-Type, which is typically text/html or text/plain. Then, HTTP header lines must be followed by a blank line.
After the headers and blank line, the rest is content that you want the user to actually see. Technically this should be proper HTML code, including <html>, <head>, and <body> tags, but it doesn't have to be — if you just print some text, as in the above example, the web browser will display it.
You will need to make sure that this file is marked as "executable" by the web server, and for convenience in testing, by you as well. The easiest way to do that is with a command like:
chmod o+x hello.ms
This uses the chmod command to set the eXecute bit for all users. Once you've done that, you should be able to run the script on the command line, by typing:
./hello.ms
...and should get the output:
Content-Type: text/html Hello world!
Now for the moment of truth! Open a web browser, and type the URL to this file into the location field. Press return. You should see:
Congratulations! You have created your very first MiniScript CGI program.
A Longer Example
Once you've successfully gotten past the "hello world" stage, creating bigger and better CGI programs is pretty easy. The following program (which I called test.ms) demonstrates several new things:
- Generating proper HTML output.
- Generating some random output (a "lucky number").
- Accessing (and in this case, displaying) environment variables.
print "Content-type: text/html"
print
print "<html><head><title>CGI Test</title>"
print "</head><body>"
print "<h1>Hello world!</h1>"
print "<p>This web page was created on the fly<br>"
print "by a MiniScript CGI</p>"
print
print "<p>Your lucky number is: " + floor(rnd * 100000) + "</p>"
print
print "<p>Environment variables:</p><table><tr><th>Key</th><th>Value</th></tr>"
for kv in env
print "<tr><td>" + kv.key + "</td><td>" + kv.value + "</td></tr>"
end for
print "</table>"
print "</body></html>"
The environment variables will be key to your success. These are used by the web server to pass information about the query to your program. For example, if you append a query string like ?foo=bar&baz=42 to your URL, you'll receive this as env.QUERY_STRING. The above program prints all the environment variables, which is really handy in testing so you can see what information is available.
Script Ideas
Now that have this new power tool in your toolbox, what will you do with it? Here are a few ideas to get the creative juices flowing:
- Create a random poetry generator that algorithmly composes a haiku, limerick, or other poem on each request.
- Make a random image server that randomly selects a picture from a directory of image files, and prints a Location response header to redirect to that file.
- Make a simple message board that stores messages (received via a POST form) in files, and serves them back up with new requests.
- Make a high score server for your Mini Micro game: using query parameters, it can take a new high score, combine it with a file of previous high scores, and serve up the current top-10 list for display in the game.
Conclusion
MiniScript and CGI are a great combination, enabling you to take your MiniScript skills to the web. Now that you know how to do it, the sky's the limit!