CHP-9>

Although mod_perl is pretty cool, it's not the only way to use Mason to build a web site. In fact, plenty of times it's more advisable to use CGI than mod_perl, as we describe in this chapter. If you find yourself in such a situation, you're in luck -- Mason works just fine under CGI, and special care has gone into making sure the cooperation is smooth. The HTML::Mason::CGIHandler module provides the glue necessary to use Mason in most common CGI environments.


CGI-Appropriate Situations

CHP-9-SECT-1>

Before we get into the details of how to set up Mason under CGI, let's think about why you might want to use this setup. After all, isn't mod_perl supposed to be better than CGI? Well, yes and no. As in most things, context is everything. The following factors may conspire to make you choose clunky old CGI (Common Gateway Interface);advantages of>

Mason;setting up under CGI (Common Gateway Interface)> CGI over clunky new mod_perl in a particular situation:

Need instant gratification

Installing mod_perl can be somewhat difficult if you've never done it before (heck, even if you have done it before), and it can take a while to get used to the peculiarities of developing in a mod_perl environment. If you want to try Mason out but don't want to spend time installing and configuring mod_perl (or you don't want to wait for the person who's going to come install it for you), you may be interested in using HTML::Mason::CGIHandler to start development, then switching over to mod_perl and HTML::Mason::ApacheHandler HTML::Mason::ApacheHandler class> once you've gotten comfortable with mod_perl.

Must share hosting environments

Many organizations simply don't have the money to pay for their own server and staff to administer it, so they sign up with a cheap virtual hosting service that lets them run CGI scripts. The key word ``virtual'' means that several organizations, inevitably of varying scruples, share the same web server on the same machine. Although some of these services say they offer mod_perl, you should not use it, because it is very insecure and very prone to catastrophic development errors.

It is insecure because all your code will run in the web server process, along with any other hooligan's code on your shared server. Unless you trust all those hooligans not to steal your passwords, harass your clients, delete your files, and plunder your village, you should avoid using mod_perl offered in a virtual hosting environment.

It is prone to development errors for the same reason: your code runs in the web server process, so if your Mason code accidentally gets into an infinite loop or hangs the server process, you bring the server down with you. Hosting services tend to dislike that. If you had enough money, you'd handle this problem by running separate servers for development and production, but you clearly don't have enough money for that, since you're using cheap virtual hosting.

Good old CGI, unpleasant as it is in other ways, provides a solution. Apache's ExecCGI mechanism (Apache)> Apache web servers;ExecCGI mechanism in> ExecCGI mechanism (and its equivalent in other servers) can be configured to use a ``setuid'' execution mechanism to make sure that your CGI scripts run as the user that owns them -- you. This means that you can make all your sensitive data files accessible only by you, that any files your scripts create are owned by you, and that if you make a big mistake, you don't anger the other people who share your server.

Of course, this argument is moot if your web hosting service doesn't support the ExecCGI model. Most good full-featured services do, and most crappy ones don't. Make sure you do the proper research.

Speed not critical

Alas, all the claims of the mod_perl crowd are true -- CGI is slower than mod_perl, and it doesn't provide nearly as much control over the server process. However, sometimes you don't care. If request speed doesn't mean too much on your site, and you don't need to do anything fancy with mod_perl's various request phases and content management, then there are few, if any, reasons to use mod_perl. mod_perl itself isn't (necessarily) all that complicated, but the environment you deploy it in can be.

A strong factor in your decision should be rigorous benchmarking; if your site running under CGI can keep up with the amount of traffic you'll need to handle, then HTML::Mason::CGIHandler holds promise for you. As always, do the proper research.

Special memory usage situations

One of the particular constraints of mod_perl is that it can use a lot of memory. This is mainly due to the persistent nature of the embedded Perl interpreter; memory you allocate during one request may not get freed until many more requests are served and the child process is terminated. Even if you explicitly free the memory when you're done with it, using Perl's undef( ) undef( ) function (Perl)> function, most operating systems won't actually return the memory block to the general pool of free system memory; they'll just mark it as reusable within that same process. Because of this, mod_perl developers are often quite miserly with memory and will sometimes do convoluted things just to keep memory usage at a minimum.

The persistence of memory creates a problem when you need to have a large chunk of data resident in memory for processing. One of the most common instances of this is HTTP file uploads>

uploads> file uploads: if the user uploads a large file, that file will often end up in memory, creating a real problem in a mod_perl environment. However, if the user is uploading a large file, he'll typically have to wait around for the file to transfer over the network, which means that he won't really care (or notice) if the receiving script takes an extra half-second to execute. CGI can be useful in this situation, because any memory used during the request will be freed up immediately when the request is over.

Web server isn't Apache

Although Apache web servers> Apache is a great and flexible web server with a huge support team and developer community, it's not the only web server on the planet. If you find yourself needing to use a server other than Apache, of course you won't be able to use mod_perl either. Since most web servers support a CGI mechanism of some sort, CGI may be the best way to use Mason in an environment like this.

In fact, even when your web server is Apache, you may want to use a different execution model like FastCGI execution model> FastCGI. Mason's __FOX_NLBF__>

__FOX_NLBF__> CGI support extends well into situations like these.


CGI-Inappropriate Situations

CHP-9-SECT-2>

In some situations, CGI (Common Gateway Interface);disadvantages of> CGI just won't do. Depending on who you ask, these situations might be characterized with terms ranging from ``always'' to ``never.'' It's beyond the scope of this book to make all the arguments germane to the CGI versus mod_perl debate, but these factors might make choosing CGI impossible:

Startup cost too great

The most commonly encountered argument in favor of mod_perl is that it reduces the startup costs> startup cost of each request by putting a Perl interpreter> Perl interpreter in resident memory, allowing various resources to be allocated once per server child rather than once per request. This is true, and important.

This resource allocation scheme can produce tremendous speedups in several areas, most notably database connection time. Many modern dynamic sites rely on a database connection, and if you're using an industrial-strength database like Oracle that has to perform lots of tasks every time you connect, connections can take so long to obtain that connecting on every request is simply unacceptable. Other resources may suffer from this same constraint, so try to determine your needs before running full speed into the CGI camp.

Advanced mod_perl features too tantalizing

Let's face it, mod_perl is cool. It's a window into the most advanced web server in the world, using the most fun and versatile language in the world. If you simply can't live without some of the more advanced mod_perl features like content negotiation, server-side subrequests, and multiple request phase hooks, you're forever going to feel fettered by CGI's inherent __FOX_NLBF__> limitations.


Creating a CGI-Based Site in Mason

CHP-9-SECT-3>

You can get Mason;creating CGI (Common Gateway Interface)-based sites in> CGI (Common Gateway Interface);creating sites in Mason> Mason and CGI to work together in several different ways. One model is to write traditional CGI scripts that use Mason as a templating language, executing Mason components from inside the CGI program. See A<CHP-9-SECT-4>``Using Mason Templates Inside Regular CGI Scripts'' for how to set this up.

A better approach to building a Mason site under CGI is to let the components drive the site. You can configure your web server to invoke a CGI script of your choosing for certain requests, and that script can begin Mason processing on those files. In other words, you can have the same set of Mason components in your site you would have under mod_perl, but those components get executed under the CGI paradigm.

Your comrade in this endeavor is the HTML::Mason::CGIHandler HTML::Mason::CGIHandler class;creating CGI-based sites with> classes;HTML::Mason::CGIHandler> module. Its role is similar to the HTML::Mason::ApacheHandler module, but since CGI is a bit clunkier than mod_perl and the CGIHandler is a bit younger than ApacheHandler, a bit more configuration is necessary. You'll need to combine four ingredients: directives in the server's configuration files (httpd.conf or .htaccess under Apache), a Mason wrapper CGI script, the Mason components themselves, and the HTML::Mason::CGIHandler module.

The necessary configuration directives are fairly straightforward. Here's an example for Apache:

  Action html-mason /cgi-bin/mason_handler.cgi
  <FilesMatch "\.html$">
   SetHandler html-mason
  </FilesMatch>

Here, the mason_handler.cgi mason_handler.cgi script> script can be located wherever you want, provided it's set up by the server to be run as a CGI script. The /cgi-bin directory:cgi-bin directory> /cgi-bin directory is already configured on most systems using the ScriptAlias directive, so that's a reasonable place to put the handler script, though it's certainly not the only place.

Instead of passing all .html files through Mason as in the previous example, you might configure the server to Masonize all files in a certain directory (use a <Directory> block for this or an .htaccess file in that directory), only certain specific files (use a <Files> block or a different <FilesMatch> <FilesMatch> pattern:FilesMatch pattern> pattern to select those files), or some more complicated scheme. See your server's documentation for more configuration help. Remember, each CGI request will take a highly nonzero time to execute, so don't process a file with Mason unless it's actually a Mason component. In particular, make sure you don't accidentally pass image files to Mason, because each web page typically contains many images, and the extra processing time for those images will be a big waste if you invoke Mason unnecessarily, not to mention that Mason may mangle those images when processing them.

Next, you need to create your mason_handler.cgi__FOX_NLBF__> script. It should be located wherever the Action directive indicates in the server configuration. Here's a mason_handler.cgi that will serve nicely for most sites. It's fairly simple, since most of the real work is done inside the HTML::Mason::CGIHandler __FOX_NLBF__> __FOX_NLBF__> module.

  #!/usr/bin/perl -w
  
  use strict;
  use HTML::Mason::CGIHandler;
  
  my $h = HTML::Mason::CGIHandler->new
    (
     data_dir  => "$ENV{DOCUMENT_ROOT}/../mason-data",
     allow_globals => [qw(%session $user)],
    );
  
  $h->handle_request;

The data_dir and allow_globals parameters should look familiar; they're just passed along to the Interpreter and Compiler, respectively. Note that the data_dir we use here may need to be changed for your setup. The main consideration is that your data_dir is somewhere outside the document root, so feel free to put it wherever makes sense for you.

Note that we didn't pass a comp_root parameter. If no comp_root is specified, HTML::Mason::CGIHandler will use $ENV{DOCUMENT_ROOT} as the document root.

With the server configuration and handler script in place, you're ready to use __FOX_NLBF__> __FOX_NLBF__> Mason. You can create a hierarchy of components for your site just as you would under a mod_perl setup.


Using Mason Templates Inside Regular CGI Scripts

CHP-9-SECT-4> CGI (Common Gateway Interface);using Mason templates in> Mason;using templates inside CGI scripts>

We have argued several times against the traditional CGI model, in which the response to each web request is driven primarily by a Perl script (or other executable programN<But who are we kidding, eh? Are you going to be writing these things in COBOL?>) that focuses on making all the logical decisions necessary for fulfilling that request. We tend to prefer template-based solutions driven by the content of the request, using concise sprinklings of programming to control the dynamic elements of the request. In other words, we prefer Mason components to CGI scripts.

However, the world is a strange place. For some odd reason, managers may not always be persuaded by the well-reasoned arguments their programmers make in favor of using Mason in its traditional way. They may even want to take an existing functional site based on badly written CGI scripts and use some basic Mason-based templating techniques to achieve the timeless goal of separating logic from presentation. In these situations, you may be called upon to use Mason as if it were one of the lightweight solutions mentioned in A<CHP-1>Chapter 1.

Luckily, you won't be the first person to want such a thing. This path has been tread often enough that it's fairly easy to use Mason as a standalone templating language. To do this, you create a Mason Interpreter, then call the Interpreter's exec( ) exec( ) method> Interpreter;exec( ) method> method, passing it either a component path or component object as the first argument.

The CGI script> CGI script in A<CHP-9-EX-1>Example 9-1 is sort of the ``Hello, World'' of dynamic web programming> dynamic web programming. It lets the user enter text in an HTML form, submit the form, and see the resultant text in the server's response.