Copyright (C) 2007 by Nik Ogura. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Bug reports and comments to





        use CGI::Lazy;

        our $q = CGI::Lazy->new({

                                        tmplDir         => "/path/to/templates",        #not off doc root

                                        jsDir           =>  "/js",                      #off doc root

                                        plugins         => {

                                                mod_perl => {

                                                        PerlHandler     => "ModPerl::Registry",

                                                        saveOnCleanup   => 1,


                                                dbh     => {

                                                        dbDatasource    => "dbi:mysql:somedatabase:localhost",
                                                        dbUser          => "dbuser",

                                                        dbPasswd        => "letmein",

                                                        dbArgs          => {"RaiseError" => 1},


                                                session => {

                                                        sessionTable    => 'SessionData',

                                                        sessionCookie   => 'frobnostication',

                                                        saveOnDestroy   => 1,

                                                        expires         => '+15m',




        print $q->header,

              $q->start_html({-style => {-src => '/css/style.css'}}),


        print $q->template('topbanner2.tmpl')->process({ logo => '/images/funkyimage.png', mainTitle => 'Funktastic', secondaryTitle => $message, versionTitle => '0.0.1', messageTitle => 'w00t!', });

        print $q->template('navbar1.tmpl')->process({

                                                one             => 'link one',

                                                one_link        => '/blah.html',

                                                two             => 'link two',

                                                two_link        => '/blah.html',

                                                three           => 'link three',

                                                three_link      => '/blah.html',

                                                four            => 'link four',

                                                four_link       => '/blah.html',


        print $q->template('fileMonkeyHelp.tmpl')->process({helpMessage => 'help text here'});

        print $q->template('fileMonkeyMain.tmpl')->process({mainmessage => "session info: <br> name: ".$q->session->data->name . "<br> time: ".$q->session->data->time});

        print $q->template('footer1.tmpl')->process({version => $q->lazyversion});


CGI::Lazy was designed to simply abstract some of the more common cgi scripting tasks because the author finally got sick of writing the same code by hand for every new site or client that comes along. It is my attempt to extend the wonderful with things that just about every modern website needs or wants, and to do it in a fairly portable manner.

There are plenty of webdev frameworks out there, many are far more full- featured. Often these solutions are so monstrous that they are overkill for small apps, or so optimized that they require full admin rights on the server they run on. CGI::Lazy was intended to be lightweight enough to run on any given server that could run perl cgi's. Of course, the more power you have, the fancier you will be able to get, so Lazy was written to be extensible and to (hopefully) play nice with whatever magic you have up your sleeve.

Lazy has also been written to be useful in a mod_perl environment if that is your pleasure. The wonders of persistence and namespaces have been (again, hopefully) all accounted for. It should plug into your mod_perl environment with little or no fuss.

For the most part, CGI::Lazy is simply a subclass of CGI::Pretty, which is an easier to read version of

We need to use CGI::Pretty due to a css issue in IE where the style definitions aren't always followed unless there is the appropriate amount of whitespace between html tags. Luckilly, CGI::Pretty takes care of this pretty transparently, and its output is easier to read and debug.

CGI::Lazy adds a bunch of hooks in the interest of not working any harder than we need to, otherwise it's a CGI::Pretty object.

Probably 80% of the apps the author has been asked to write have been front ends to some sort of database, so that's definitely the angle Lazy is coming from. It works just fine with no db, but most of the fancy work is unavailable.

Output to the web is intended to be through templates via HTML::Template. However, if you want to write your content into the code manually, we won't stop you. Again, the whole point was to be flexible and reusable, and to spend our time writing new stuff, not the same old crap over and over again.

The CGI::Lazy::Widget::Dataset module especially was written to bring spreadsheet-like access to a database table to the web in a fairly transparent manner- after all, most of the time you're doing one of 4 operations on a database: select, insert, update, delete. The Dataset is, at least at the time of the original writing, the crown jewel of the Lazy framework. The templates for a Dataset are pretty complicated, and are tied pretty tightly to the Javascript that controls them on the client side. Because nobody (especially the author) wants to write these monsters from scratch every time a new Widget is called for, the CGI::Lazy::Template::Boilerplate class exists to generate boring, but functional templates for your Widgets. The boilerplate templates give you a functional starting place. After that, it's up to you.

In any event, it is my hope that this is useful to you. It has saved me quite alot of work. I hope that it can do the same for you. Bug reports and comments are always welcome.


authn ()

Returns authentication object

authz ()

Returns authorization object

config ()

Method retrieves CGI::Lazy::Config object for configuration variable retrieval See CGI::Lazy::Config for details

db ()

Method retrieves the database object CGI::Lazy::DB. The db object contains convenience methods for database access, and will contain the default database handle for the object.

dbh ()

Retrieves dbh from db object for use in cgi. Convenience method. Same as $q->db->dbh.

errorHandler ()

Returns the CGI::Lazy::ErrorHandler object. ErrorHandler contains convenience methods for trapping and returning error codes without generating a pesky 500 error.

header (args)

Creates standard http header. Passes all arguments to CGI::Pretty::header, simply adding our own goodness to it in passing.


normal header args

javascript ( )

returns CGI::Lazy::Javascript object.

see CGI::Lazy::Javascript for details.

jswrap ( script )

Wraps javascript text in script tags and html comments for output to the browser. Pretty much the same as $q->script, but it comment wraps the script contents.


javascript text to output to the browser.

mod_perl ()

Returns mod_perl object if plugin is enabled.

See CGI::Lazy::ModPerl for details

new ( args )

Constructor. Creates the instance of the CGI::Lazy object.


If args is a hashref, it will assume that the hash is the config.

If it's just a string, it's assumed to be the absolute path to the config file for the Lazy object. That file will be parsed as JSON.

        tmplDir         => Directory where Lazy will look for html templates.  Absolute path to directory.

        buildDir        => Directory where Lazy will build template stubs.  Absolute path to directory.

        jsDir           => Directory where Lazy will look for javascript.  Path relative to document root.

        cssDir          => Directory where Lazy will look for css.  Path relative to document root.

        noMinify        => By default javascript is minified before output- all whitespace is removed.  This speeds things up mightily, but can make for difficult debugging.  
                           Set this to a true value, and javascript will be printed with all whitespace intact.

        silent          => Set to a true value, and internal errors will not be printed to STDERR.  Defaults to false.

        plugins         => Optional components

                mod_perl => mod_perl goodness

                dbh     => Lazy handles database connection

                dbhVar  => name of variable that holds database handle created elsewhere

                session => stateful sessions (requires database)

lazyversion ()

returns version of CGI::Lazy.

plugin ()

Returns plugin object.

see CGI::Lazy::Plugin for details.


Returns the session object see CGI::Lazy::Session for details.

template ()

Returns CGI::Lazy::Template object, or if it hasn't been created yet, creates it and returns it.

See CGI::Lazy::Template for details.

util ()

Returns CGI::Lazy::Utility object

See CGI::Lazy::Utility for details.

vars ()

Returns hashref to the variables used in creating the object.

widget ()

returns the CGI::Lazy::Widget object


Subversion repository available at:

A collection of demo scripts are available at: