Introduction

In this three part tutorial series we'll learn about RevOnRockets and how it can help you create web applications. The topics covered will be: using the RevHTTP server, using RocketsDebug and using stacks for Web Applications. Today we will explore using the RevHTTP server.

This is just the tip of the iceberg, there's more to talk about in future articles but now, let us get this going! We as xTalk programmers have enjoyed a productivity level that few developers can relate to, maybe just Forth and LISP coders can share our experience of building software while you use it, in an elegant and iterative process. From the comfort of our IDE we can develop and grow stacks, functions and objects as we need them, never stopping for compilation or to debug as if those phases were a separate thing. While other developers using other tools need to design, implement, compile and test (...rinse, repeat), we have a unique flow that enables us to develop faster and usually better (and with GLX2 it gets even better!!!)

Now, until RevOnRockets appeared, all these benefits we're used to were not present when developing web applications. To create such applications we needed to use a text editor to build text file scripts, upload them to our server, try to run it, watch it die, look through lots of system log files and our own text file debugging to find out where the bug was. In one Revolution Conference, I labelled this process the "code-upload-explode". I don't like it and I bet you don't like it either. I wanted an easy way to build web applications in which I could use the points I like most about Revolution: no need to build an application to test it, no need to stop an application to debug it, be able to develop while running and use stacks and Transcript. RevOnRockets puts the fun back into web application development.

At a glance, RevOnRockets is a collection of three things: a web server, cgi building libraries and examples. The web server runs inside the Revolution IDE and is compatible with Revolution based CGIs, so instead of uploading to a far away server to test an application, you can do it locally from inside the IDE. This alone is useful but when you discover that you can also use the debugger, this becomes a blessing. Creating a web application often needs the same stuff over and over again, so the cgi building libraries included help you by providing common useful functions. The examples show how to use the libraries and server.

Now, let the web games begin.

Unpacking and running RevOnRockets

First download it, This is a zip file, you can unzip it anywhere you want. In the RevOnRockets folder, you'll see a folder called "www". That's where the action happens. This folder is your root web folder, your cgi apps and web pages will be inside that folder. Besides that folder you'll see the RevHTTP stack which is named "HTTP.Rev". Open it.

Using the RevHTTP stack is really easy. Check the "setup" tab to see if you're happy with the port selection. The default port is 8082, if you are happy with this, just go back to the main tab and click "start". Clicking this will bring your default web browser up with a welcome page. If you're seeing the welcome page then everything is working correctly.

Creating the Hello Web cgi

No web development tutorial is complete without a simple "Hello World" cgi. So let us build it. Open the "www" folder and inside it you'll notice lots of examples and some other folders. When you check the welcome page URL, you'll see something like "http://localhost:8082" which means, the local machine on port 8082. You'll see that the welcome html page is inside the "www" folder and is called "index.html", this page is the default page that is displayed when the client requests a folder but doesn't specify the page he wants. In the case of the welcome page, the client specifies the "/" root folder, so RevHTTP looks for "www/index.html". You can test by creating a simple text file inside that folder and naming it "test.txt", if you go to "http://localhost:8082/test.txt", you'll see your file content.

Moving along, you see that inside the "www" folder, there is a folder called "cgi-bin", this is a very special folder, for it contains the web applications (aka CGI). While the "www" folder is suited for holding static content such as images and html pages, the "cgi-bin" folder is made to hold your scripts. Let us build a text file inside "www/cgi-bin/" called "helloweb.cgi". Note that even though the file has a cgi extension, it still a simple text file. Create a text file and put this in it:

#!revolution -ui

global gDataA

on startup
start using "RocketsCGI.rev"

cgiOutput "Hello Web from Runtime Revolution", "text/plain"
end startup

Now access the URL http://localhost:8082/cgi-bin/helloweb.cgi and you'll see a plain text display which reads "Hello Web from Runtime Revolution". When the browser requests that file, RevHTTP executes its content and its output is sent to the browser.

Let us examine it line by line.

The first line is a unix shee-bang specifier that flags that the script in the text file is to be run using Revolution. The dash "ui" option tells revolution not to load the graphical user interface.

gDataA is a global array created by the RocketsCGI library. Although we don't use it in this demo, I've included it out of habit. It holds all kinds of information, including the parameters passed in the URL and on POST request.

The startup handler is the first one that is called, so it makes sense to put our logic inside it. For text scripts, it is actually the only one that is called, there's no openstack or opencard, just startup.

We put into use the library known as RocketsCGI (and previously known as EasyCGI). This is a core function library for cgis providing basic features such as cgiOutput function which can send data back to the browser using the correct format. The first parameter is the content you're sending back, the second is the mime type of the content.

With this, you created your first CGI. If you copied both "helloWeb.cgi" and "RocketsCGI.rev" to your apache web server, it would work the same.

Next time we will look at how to debug your web application.