# Programming Ruby ### The Pragmatic Programmer's Guide
Previous < | Contents ^ | Next >

# Ruby and the Web

Ruby is no stranger to the Internet. Not only can you write your own SMTP server, FTP daemon, or Web server in Ruby, but you can also use Ruby for more usual tasks such as CGI programming or as a replacement for PHP.

## Writing CGI Scripts

You can use Ruby to write CGI scripts quite easily. To have a Ruby script generate HTML output, all you need is

    #!/usr/bin/env ruby
    print "HTTP/1.0 200 OK\r\n"
    print "Content-type: text/html\r\n\r\n"
    print "<html><body>Hello World!</body></html>\r\n"

You could use Ruby's regular expression features to parse incoming query strings, look up environment variables, check tags, substitute text into templates, escape special characters, format up the HTML, and print it all out.

Or, you could use class `CGI`.

### Using cgi.rb

Class `CGI` provides support for writing CGI scripts. With it, you can manipulate forms, cookies, and the environment, maintain stateful sessions, and so on. It's documented in full in the reference section beginning on page 497, but we'll take a quick look at its capabilities here.

### Quoting

When dealing with URLs and HTML code, you must be careful to quote certain characters. For instance, a slash character (``/'') has special meaning in a URL, so it must be ``escaped'' if it's not part of the path name. That is, any ``/'' in the query portion of the URL will be translated to the string ```%2F`'' and must be translated back to a ``/'' for you to use it. Space and ampersand are also special characters. To handle this, `CGI` provides the routines `CGI.escape` and `CGI.unescape`:

    require 'cgi'
    puts CGI.escape( "Nicholas Payton/Trumpet & Flugel Horn" )

produces:

    Nicholas+Payton%2FTrumpet+%26+Flugel+Horn

Similarly, you may want to escape HTML special characters:

    require 'cgi'
    puts CGI.escapeHTML( '<a href="/mp3">Click Here</a>' )

produces:

    &lt;a href=&quot;/mp3&quot;&gt;Click Here&lt;/a&gt;

To get really fancy, you can decide to escape only certain elements within a string:

    require 'cgi'
    puts CGI.escapeElement('<hr><a href="/mp3">Click Here</a><br>','A')

produces:

    <hr>&lt;a href=&quot;/mp3&quot;&gt;Click Here&lt;/a&gt;<br>

Here only the ```A`'' tag is escaped; other tags are left alone. Each of these methods has an ```un`-'' version to restore the original string.

### Forms

Using class `CGI` gives you access to HTML query parameters in two ways. Suppose we are given a URL of `/cgi-bin/lookup?player=Miles%20Davis&year=1958`. You can access the parameters ```player`'' and ```year`'' using `CGI#[]` directly:

`require 'cgi'`
`cgi = CGI.new`
`cgi['player']` | » | `["Miles Davis"]`
`cgi['year']` | » | `["1958"]`

Or, you can retrieve all parameters as a `Hash`:

`require 'cgi'`
`cgi = CGI.new`
`h = cgi.params`
`h['player']` | » | `["Miles Davis"]`

### Creating Forms and HTML

`CGI` contains a huge number of methods used to create HTML---one method per tag. In order to enable these methods, you must create a `CGI` object by calling `CGI.new`, passing in the required level of HTML. For these examples, we'll use ```html3`''.

To make tag nesting easier, these methods take their content as code blocks. The code blocks should return a `String`, which will be used as the content for the tag. For this example, we've added some gratuitous newlines to make the output fit on the page.

    require "cgi"
    cgi = CGI.new("html3")  # add HTML generation methods
    cgi.out{
      cgi.html{
        cgi.head{ "\n"+cgi.title{"This Is a Test"} } +
        cgi.body{ "\n"+
          cgi.form{"\n"+
            cgi.hr +
            cgi.h1 { "A Form: " } + "\n"+
            cgi.textarea("get_text") +"\n"+
            cgi.br +
            cgi.submit
          }
        }
      }
    }

produces:

    Content-Type: text/html
    Content-Length: 302

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML><HEAD>
    <TITLE>This Is a Test</TITLE></HEAD><BODY>
    <FORM METHOD="post" ENCTYPE="application/x-www-form-urlencoded">
    <HR><H1>A Form: </H1>
    <TEXTAREA NAME="get_text" ROWS="10" COLS="70"></TEXTAREA>
    <BR><INPUT TYPE="submit"></FORM></BODY></HTML>

This code will produce an HTML form titled ``This Is a Test,'' followed by a horizontal rule, a level-one header, a test input area, and finally a submit button. When the submit comes back, you'll have a CGI parameter named ```get_text`'' containing the text the user entered.

### Cookies

You can store all kinds of interesting stuff on an unsuspecting surfer's machine using cookies. You can create a named cookie object and store a number of values in it. To send it down to the browser, set a ``cookie'' header in the call to `CGI#out`.

    require "cgi"
    cookie = CGI::Cookie.new("rubyweb", "CustID=123", "Part=ABC");
    cgi = CGI.new("html3")
    cgi.out( "cookie" => [cookie] ){
      cgi.html{
        "\nHTML content here"
      }
    }

produces:

    Content-Type: text/html
    Content-Length: 86
    Set-Cookie: rubyweb=CustID%3D123&Part%3DABC; path=

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML>
    HTML content here</HTML>

The next time the user comes back to this page, you can retrieve the cookie values for `CustID` and `Part`, as shown in the HTML output.

    require "cgi"
    cgi = CGI.new("html3")
    cgi.out{
      cgi.html{
        cgi.pre{
          cookie = cgi.cookies["rubyweb"]
            "\nCookies are\n" + cookie.value.join("\n")
        }
      }
    }

produces:

    Content-Type: text/html
    Content-Length: 111

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML><PRE>
    Cookies are
    CustID=123
    Part=ABC</PRE></HTML>

### Sessions

Cookies by themselves still need a bit of work to be useful. What we really want is a session: a persistent state for some Web surfer. Sessions are handled with `CGI::Session` (documented beginning on page 504), which uses cookies but provides a higher-level abstraction.

    require "cgi"
    require "cgi/session"

    cgi = CGI.new("html3")
    sess = CGI::Session.new( cgi, "session_key" => "rubyweb",
                              "session_id"  => "9650",
                              "new_session" => true,
                              "prefix" => "web-session.")
    sess["CustID"] = 123
    sess["Part"] = "ABC"

    cgi.out{
      cgi.html{
        "\nHTML content here"
      }
    }

This will send a cookie to the user named ``rubyweb'' with a value of 9650. It will also create a disk file in `$TMP/web-session.9650` with the key, value pairs for `CustID` and `Part`.

When the user returns, all you need is a parameter to indicate the session id. In this example, that would be `rubyweb=9650`. With that value in the parameters, you'll be able to retrieve the full set of saved session data.

    require "cgi"
    require "cgi/session"

    cgi = CGI.new("html3")
    sess = CGI::Session.new( cgi, "session_key" => "rubyweb",
                                   "prefix" => "web-session.")
    cgi.out{
      cgi.html{
        "\nCustomer #{sess['CustID']} orders an #{sess['Part']}"
      }
    }

## Embedding Ruby in HTML

So far we've looked at using Ruby to create HTML output, but we can turn the problem inside out; we can actually embed Ruby in an HTML document.

There are a number of packages that allow you to embed Ruby statements in some other sort of a document, especially in an HTML page. Generically, this is known as ``eRuby.'' Specifically, there are several different implementations of eRuby, including `eruby` and `erb`. The remainder of this section will discuss `eruby`, written by Shugo Maeda.

Embedding Ruby in HTML is a very powerful concept---it basically gives us the equivalent of a tool such as ASP, JSP, or PHP, but with the full power of Ruby.

### Using eruby

`eruby` acts as a filter, plain and simple. Any text within the input file is passed through untouched, with the following exceptions:

Expression | Description
`<%` ruby code `%>` | The Ruby code between the delimiters is replaced with its output.
`<%=` ruby expression `%>` | The Ruby expression between the delimiters is replaced with its value.
`<%#` ruby code `%>` | The Ruby code between the delimiters is ignored (useful for testing).

You invoke `eruby` as:

    eruby [
                options
                ] [
                document
                ]

If the document is omitted, `eruby` will read from standard input. The command-line options for `eruby` are shown in Table 14.1 on page 149.

Command-line options for `eruby`
Option | Description
`-d`, `--debug` | Sets $DEBUG to `true`.
`-K` kcode | Specifies an alternate coding system (see page 137).
`-M` mode | Specifies runtime mode, one of:
`f` | filter mode
`c` | CGI mode (prints errors as HTML, sets $SAFE=1)
`n` | NPH-CGI mode (prints extra HTTP headers, sets $SAFE=1)
`-n`, `--noheader` | Disables CGI header output.
`-v`, `--verbose` | Enables verbose mode.
`--version` | Prints version information and exits.

Let's look at some simple examples. We'll run the `eruby` executable on the following input.

    This text is <% a = 100; puts "#{a}% Live!" %>

`eruby` substitutes the expression between the delimiters and produces

    This text is 100% Live!

Using the <%= form acts as if you printed the value of the expression. For instance, the input

    <%a = 100%>This text is almost <%=a%> degrees! Cool!

replaces the `=a` with the value of `a`.

    This text is almost 100 degrees! Cool!

And, of course, you can embed Ruby within a more complex document type, such as HTML.

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
    <html>
    <head>
    <title>eruby example</title>
    </head>
    <body>
    <h1>Enumeration</h1>
    <ul>
    <%(1..10).each do|i|%>
      <li>number <%=i%></li>
    <%end%>
    </ul>
    <h1>Environment variables</h1>
    <table>
    <%ENV.keys.sort.each do |key|%>
      <tr>
        <th><%=key%></th><td><%=ENV[key]%></td>
      </tr>
    <%end%>
    </table>
    </body>
    </html>

### Installing eruby in Apache

You can set up an Apache Web server to automatically parse Ruby-embedded documents using eRuby, much in the same way that PHP does. You create Ruby-embedded files with an ```.rhtml`'' suffix and configure the Web server to run the `eruby` executable on these documents to produce the desired HTML output.

In order to use `eruby` with the Apache Web server, you need to perform the following steps.

- Copy the `eruby` binary to the `cgi-bin` directory.

- Add the following two lines to `httpd.conf`:

      AddType application/x-httpd-eruby .rhtml
      Action application/x-httpd-eruby /cgi-bin/eruby

- If desired, you can also add or replace the `DirectoryIndex` directive such that it includes `index.rhtml`. This lets you use Ruby to create directory listings for directories that do not contain an `index.html`. For instance, the following directive would cause the embedded Ruby script `index.rhtml` to be searched for and served if neither `index.html` nor `index.shtml` existed in a directory.

      DirectoryIndex index.html index.shtml index.rhtml

  Of course, you could also simply use a site-wide Ruby script as well.

      DirectoryIndex index.html index.shtml /cgi-bin/index.rb

And that's it! You can now write HTML documents that contain embedded Ruby to generate forms and content dynamically. Be sure to see also the Ruby `CGI` library, which is documented beginning on page 497.

## Improving Performance

You can use Ruby to write CGI programs for the Web, but, as with most CGI programs, the default configuration has to start up a new copy of Ruby with every cgi-bin page access. That's expensive in terms of machine utilization and can be painfully slow for Web surfers. The Apache Web server solves this problem by allowing loadable modules.

Typically, these modules are dynamically loaded and become part of the running Web server process---there is no need to spawn another interpreter over and over again to service requests; the Web server is the interpreter.

And so we come to `mod_ruby` (available from the archives), an Apache module that links a full Ruby interpreter into the Apache Web server itself. The `README` file included with `mod_ruby` provides details on how to compile and install it.

Once installed and configured, you can run Ruby scripts just like you could without `mod_ruby`, except that now they will come up much faster.

Previous < | Contents ^ | Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/)).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.