NAME

It is primarily a glue between HTML::Template, CGI::Session, CGI, Locale::Maketext and some magic :)

SYNOPSIS

  use CGI::Framework;
  use vars qw($f);
  
  #
  # Setup the initial framework instance
  #
  $f = new CGI::Framework (
          sessions_dir          =>      "/tmp",
          templates_dir         =>      "/home/stuff/myproject/templates",
          initial_template      =>      "enterusername",
  )
  || die "Failed to create a new CGI::Framework instance: $@\n";

  #
  # Get the instance to "do it's magic", including handling the verification of the
  # just-submitting form, preparing the data for the upcoming template to be sent, and any cleanup
  #
  $f->dispatch();

  #
  # This sub is automatically called after the "enterusername" template is submitted by the client
  #
  sub validate_enterusername {
          my $f = shift;
          if (!$f->form("username")) {
                  $f->add_error("You must enter a username");
          }
          elsif (!$f->form("password")) {
                  $f->add_error("You must enter your password");
          }
          else {
                  if ($f->form("username") eq "mina" && $f->form("password") eq "verysecret") {
                          $f->session("username", "mina");
                          $f->session("authenticated", "1");
                  }
                  else {
                          $f->add_error("Authentication failed");
                  }
          }
  }

  #
  # This sub is automatically called before the "mainmenu" template is sent
  #
  sub pre_mainmenu {
          my $f = shift;
          $f->assert_session("authenticated");
          $f->html("somevariable", "somevalue");
          $f->html("name", $f->session("username"));
  }

  #
  # This sub is automatically called after the "logout" template is sent
  #
  sub post_logout {
          my $f = shift;
          $f->clear_session();
  }

DESCRIPTION

CONCEPTUAL OVERVIEW

• The client sends an initial GET request to the web server
• The CGI recognizes that this is a new client, creates a new session, sends the session ID to the client in the form of a cookie, followed by sending a pre-defined initial template
• The user interacts with the template, filling out any form elements, then re-submits the form back to the CGI
• The CGI reloads the session based on the client cookie, validates the form elements the client is submitting. If any errors are found, the client is re-sent the previous template along with error messages. If no errors were found, the form values are either acted on, or stored into the session instance for later use. The client is then sent the next template.
• The flow of templates can either be linear, where there's a straight progression from template 1 to template 2 to template 3 (such as a simple ordering form) or can be non-linear, where the template shown will be based on one of many buttons a client clicks on (such as a main-menu always visible in all the templates)
• Sessions should automatically expire if not loaded in X amount of time to prevent unauthorized use.

IMPLEMENTATION OVERVIEW

• Writing the stub code as per the SYNOPSIS. This entails creating a new CGI::Framework instance, then calling the dispatch() method.
• Creating your templates in the templates_dir supplied earlier. Templates should have the .html extension and can contain any templating variables, loops, and conditions described in the HTML::Template documentation.
• For each template created, you can optionally write none, some or all of the needed perl subroutines to interact with it. The possible subroutines that, if existed, will be called automatically by the dispatch() method are:

STARTING A NEW PROJECT

The following steps should be taken to start a new project:

SETUP DIRECTORY STRUCTURE

This is the recommended directory structure for a new project:

CONFIGURE YOUR WEB SERVER

How to do this is beyond this document due to the different web servers out there, but in summary, you want to create a new virtual host, alias the document root to the above public_html/ directory, alias /cgi-bin/ to the above cgi-bin/ directory and make sure the server will execute instead of serve files there, and in theory you're done.

CREATE TEMPLATES

You will need to create a template for each step you want your user to see. Templates are regular HTML pages with the following additions:

ASSOCIATE THE CODE WITH THE TEMPLATES

For each template you created, you might need to write a pre_templatename() sub, a post_templatename() sub and a validate_templatename() sub as described earlier. None of these subs are mandatory.

For clarity and consistency purposes, the pre_templatename() and post_templatename() subs should go into the pre_post.pm file, and the validate_templatename() subs should go into the validate.pm file.

There are also 4 special sub names. pre__pre__all(), post__pre__all(), pre__post__all() and post__post__all(). If you create these subs, they will be called before pre_templatename(), after pre_templatename(), before post_templatename() and after post_templatename() respectively for all templates.

WRITE YOUR CGI

Copying the SYNOPSIS into a new CGI file in the cgi-bin/ directory is usually all that's needed unless you have some advanced requirements such as making sure the user is authenticated first before allowing them access to certain templates.

TEST, FINE TUNE, ETC . . .

Every developer does this part, right :) ?

STARTING A NEW PROJECT FOR THE IMPATIENT

• Install this module
• Run: perl -MCGI::Framework -e 'CGI::Framework::INITIALIZENEWPROJECT "/path/to/your/project/base"'
• cd /path/to/your/project/base

  Customize the stubs that were created there for you. Refer back to the not-so-impatient section above for clarifications of anything you see there.

OBJECT-ORIENTED VS. FUNCTION MODES

THE OBJECT-ORIENTED WAY

As the examples show, this is the object-way of doing things:

        use CGI::Framework;

        my $instance = new CGI::Framework (
                this    =>      that,
                foo     =>      bar,
        );

        $instance->dispatch();

        sub validate_templatename {
                my $instance = shift;
                if (!$instance->form("country")) {
                        $instance->add_error("You must select a country");
                }
                else {
                        $instance->remember("country");
                }
        }

        sub pre_templatename {
                my $instance = shift;
                $instance->html("country", [qw(CA US BR)]);
        }
    

THE FUNCTION-BASED WAY

The function-based way is very similar (and slightly less cumbersome to use due to less typing) than the OO way. The differences are: You have to use the ":nooop" tag in the use() line to signify that you want the methods exported to your namespace, as well as use the initialize_cgi_framework() method to initialize the instance instead of the new() method in OO mode. An example of the function-based way of doing things:

        use CGI::Framework ':nooop';

        initialize_cgi_framework (
                this    =>      that,
                foo     =>      bar,
        );

        dispatch();

        sub validate_templatename {
                if (!form("country")) {
                        add_error("You must select a country");
                }
                else {
                        remember("country");
                }
        }

        sub pre_templatename {
                html("country", [qw(CA US BR)]);
        }
    

THE CONSTRUCTOR / INITIALIZER

new(%hash)

This is the standard object-oriented constructor. When called, will return a new CGI::Framework instance. It accepts a hash (or a hashref) with the following keys:

initialize_cgi_framework(%hash)

Just like the above new() constructor, except used in the function-based approach instead of the object-oriented approach.

METHODS / FUNCTIONS

add_error($scalar [, @array ] )

This method accepts a scalar error and adds it to the list of errors that will be shown to the client. It should only be called from a validate_templatename() subroutine for each error found during validating the form. This will cause the dispatch() method to re-display the previous template along with all the errors added.

If you specified the "valid_languages" and the "maketext_class_name" keys to the initializer, the error message you give to this method will be localized to the user's preferred language (or the default language) before being showed to the user. Refer to the "INTERNATIONALIZATION AND LOCALIZATION" section. If this is the case, you may specify extra arguments after the main $scalar, and they will be passed verbatim to Locale::Maketext's maketext() method - this is often used to localize variables within a sentence.

assert_form(@array)

This method accepts an array of scalar values. Each element will be checked to make sure that it has been submitted in the just-submitted form and has a true value. If any elements aren't found or have a false value, the missinginfo template is shown to the client. The missinginfo template will be passed special variables _missing_info and _missing_info_caller which you can use to display details about the failed assertions. Refer to the "PRE-DEFINED TEMPLATE VARIABLES" section for more info.

assert_session(@array)

Just like the assert_form() method, except it checks the values against the session instead of the submitted form.

clear_session

This method deletes all the previously-stored values using the session() or remember() methods.

dispatch

This method is the central dispatcher. It calls validate_templatename on the just-submitted template, checks to see if any errors were added with the add_error() method. If any errors were added, re-sends the client the previous template, otherwise sends the client the template they requested.

finalize

This method undefs some internal references that prevent the object from being destroyed. It's called automatically for you when show_template() is done or if there's a fatal error, so there is usually no need to call it manually.

This method exit()s when done - it does not return.

form($scalar)

This method accepts an optional scalar as it's first argument, and returns the value associated with that key from the just-submitted form from the client. If no scalar is supplied, returns all entries from the just-submitted form.

get_cgi_object

Returns the underlying CGI object. To be used if you'd like to do anything fancy this module doesn't provide methods for, such as processing extra cookies, etc...

get_cgi_session_object

Returns the underlying CGI::Session object. To be used if you'd like to do anything fancy this module doesn't provide methods for.

html($scalar, $scalar)

This method accepts a scalar key as it's first argument and a scalar value as it's second. It associates the key with the value in the upcoming template. This method is typically called inside a pre_template() subroutine to prepare some dynamic variables/loops/etc in the templatename template.

html_push($scalar, $scalar)

Very similar to the above html() method, except it treats the key's value as an arrayref (creates it as an arrayref if it didn't exist), and push()es the value into that array. This method is typically used to append to a key that will be used in a template loop with HTML::Template's <TMPL_LOOP> tag, the value in which case is normally a hashref.

html_unshift($scalar, $scalar)

Very similar to the above html_push() method, except it unshift()s instead of push()es the value.

log_this($scalar)

This method accepts a scalar message and logs it to the filename specified in the log_filename parameter in the new constructor. You can not use this method if you have not supplied a log_filename setting to the constructor.

remember($scalar [, $scalar])

This method accepts a mandatory scalar source key name as it's first argument and an optional scalar destination key name as it's second argument . It then treats that source scalar as a key in the just-submitted form, and saves that key-value pair into the session. This method is simply shorthand for saying:

        $instance->session($sourcekeyname, $instance->form($sourcekeyname));
    

If the second optional parameter is supplied, then that destination key is used in the session. This allows the key saved in the session to have a different name than the one submitted in the form. In that case, this method becomes a shorthand for:

        $instance->session($destinationekeyname, $instance->form($sourcekeyname));
    

It is frequently used to premanently save a submitted form key+value inside the validate_templatename() sub after it has been checked for correctness.

return_template($scalar)

This method accepts a scalar template name, and returns the content parsed from that template suitable for sending to the client. Internally it takes care of language substitution, and the <cgi_framework_header>, <cgi_framework_footer> tags.

In scalar context it returns the content suitable for sending to the client. In array context it returns the content and the content-type.

session($scalar [, $scalar])

This method accepts a scalar key as it's first argument and an optional scalar value as it's second. If a value is supplied, it saves the key+value pair into the session for future retrieval. If no value is supplied, it returns the previously-saved value associated with the given key.

show_template($scalar [, $nofinalize])

This method accepts a scalar template name, calls the pre__pre__all() sub if found, calls the pre_templatename() sub if found, calls the post__pre__all() sub if found, sends the template to the client, calls the pre__post__all() sub if found, calls the post_templatename() sub if found, calls the post__post__all() sub if found, then exits. Internally uses the return_template() method to calculate actual content to send.

Note: This method calls finalize() when done unless $nofinalize is set to true. You probably never want to do this, in which case the call to finalize() will cause this method to never return.

PRE-DEFINED TEMPLATE VARIABLES

_current_template

This variable will contain the name of the current template

_fatal_error

This variable will contain the error message that caused a fatal error. It will only be available when a fatal error occurs and the fatal error template specified by the fatal_error_template constructor argument is being shown.

_form_action

This variable will contain the URL to the current CGI

_missing_info

This variable will only be available when the missinginfo template is being called from a call to assert_form() or assert_session() methods. It's value will be an arrayref of hashes. Each hash will have a key named "name", the value of which is the name of a key supplied to assert_form() or assert_session() that failed the assertion. This variable can be used with HTML::Template's TMPL_LOOP macro to display the variables that failed the assertion.

_missing_info_caller

This variable will only be available when the missinginfo template is being called from a call to assert_form() or assert_session() methods. It's value will be a scalar describing the caller of assert_form() or assert_method().

INTERNATIONALIZATION (i18n) AND LOCALIZATION (l10n)

• Content inside one of the templates
• Errors added via the add_error() method

Multi-language support is initiated by you by supplying the "valid_languages" arrayref to the CGI::Framework constructor. This arrayref should contain a list of language tags you wish to support in your application. These tags are not necessarily the exact same tags as the ISO-specified official language tag, and as a matter of fact it is recommended that you use tags that are as short as possible for reasons that will be apparent below.

As an example, if you intend to support English and French in your application, supplying this to the constructor would indicate that:

        "valid_languages"       =>      ['en', 'fr'],

When the module sends output to the user, it will try to send the "appropriate" language localization.

What is the "appropriate" language localization to send ?

The module uses a fairly simple logic to determine which is the language localization to send:

The session variable "_lang"

If the session variable "_lang" is set, it will be used as the user's desired localization.

You can either populate this variable manually in your code, such as by:

        session("_lang", "en");
    

Or more conveniently, let CGI::Framework handle that job for you by having the templates set a form element named "_lang". This allows you to add to a top-header template a "Switch to English" button that sets the form element "_lang" to "en", and a "Switch to French" button that sets the form element "_lang" to "fr".

When CGI::Framework is processing the submitted form and notices that the form element "_lang" is set, it will update the session's "_lang" correspondingly, hence setting that user's language.

The default language

If the session variable "_lang" is not set as described above, the default language that will be used is the first language tag listed in the "valid_languages" arrayref.

Finally, this is how to actually define your multi-lingual content:

Localizing content inside the templates

This is where pleasantness begins. The language tags you defined in the "valid_languages" constructor key can be used as HTML tags inside the templates! CGI::Framework will take care of parsing and presenting the correct language and illiminating the others. An example in a bilingual template:

        <en>Good morning!</en>
        <fr>Bonjour!</fr>
    

Localizing errors added via the add_error() method

By default, errors you add via the add_error() method will not be localized and will be passed straight-through to the errors template and shown as-is to the end user.

To enable localization for the errors, you will need to, aside from supplying the "valid_languages" key, also supply the "maketext_class_name" key to the constructor. This should be the name of a class that you created. CGI::Framework will take care of use()ing that class. For example:

        "maketext_class_name"   =>      "MyProjectLocalization",
    

Exactly what should be in that class ? This is where I direct you to read Locale::Maketext. This class is your project's base localization class. For the impatient, skip down in Locale::Maketext's POD to the "HOW TO USE MAKETEXT" section. Follow it step by step except the part about replacing all your print() statements with print maketext() - this is irrelevant in our scenario.

After you do the above, your calls to the add_error() method will be automatically localized, using Locale::Maketext and your custom localization class. In our example here, you would end up with:

BUGS

AUTHOR

        Mina Naguib
        CPAN ID: MNAGUIB
        mnaguib@cpan.org
        http://mina.naguib.ca

COPYRIGHT

The full text of the license can be found in the LICENSE file included with this module.

Copyright (C) 2003-2005 Mina Naguib.

SEE ALSO