view release on metacpan or  search on metacpan

lib/CGI/Builder.pm  view on Meta::CPAN

The CBF implements a pre-structured and customizable CGI process, subdivided in phases to allow maximum process resolution and control. (see L<"Process Phases">)

=item * Memory Efficient

The whole CGI::Builder module is written in just 210 lines of code, very fast to load, very small footprint and very easy to maintain ;-). (see L<"Internal Structure">)

=item * Homogeneous Accessors

The programmer has just to learn the features of a couple of accessors (property and property group) to be able to use dozens of different accessors with the same friendly and consistent interface. (see L<"PROPERTY ACCESSORS"> and L<"PROPERTY GROUP A...

=item * OOTools pragmas

When using OOTools, adding lots of new custom properties accessors or accessors added by extensions will practically not increase neither the loading time nor the memory reqirements. (see "Function Templates" in the F<perlref> manpage)

=item * Smart defaults always overridable

The default of this framework are usually smart enough to do the right job for you even without any specific assignation, anyway you can always easily override everything with your own code. (see L<"Overriding"> and L<"ADVANCED FEATURES">)

=item * Powerful and flexible extension system

The CBF extension system allows L<"Inheritance, Overriding and Overrunning"> which greatly simplify the development and the use of any super class or extension.

=item * Growing Extensions List

Your application can take the advantage of a broad L<"Extensions List"> already covering most needed tasks (and hopefully growing with the contribution of many authors).

=item * Consistent interface and internal structure

The internal structure mirrors the public interface, so no mistakes about public or private methods and keys which often cause conflict in other frameworks. (see L<"Internal Structure">)

=item * Clear Conventions and Guide Lines

The CBF clearly states the conventions and the guide lines to use in your code or in extensions, making it very simple to avoid clashes and inconsistency even with future extensions. (see L<"HOW TO...">)

=back

=head2 Concept

In a (very simplified) web client-server transaction, when a client requests a static html page to the server, the server sends that page to the client; when the object of the request is a CGI script, that script is supposed to somehow create the 'pa...

B<Note>: In the CBF metaphor, the page concept is not strictly related with the HTML file concept: 'page' is just the most used name of the entity that is the object of the request/response transaction, and so we use it as a simple synonym of request...

The CBF metaphor is constructed around this simple concept: the web application using the CBF is interfaced with the client through 'pages'. A B<page> (page_name) is requested by the client and a B<page> (page_content) is sent to the client as the re...

The application process is segmented into L<"Process Phases"> which will call specific L<"Handlers"> to allow your application to execute code at specific time during the process.

B<Note>: You will find this technique very familiar if you have some knowledge about mod_perl handlers.

As for most CGI frameworks, a complete CGI application is usually composed by 2 parts: B<The Instance Script> and B<CGI Builder Build (CBB)>.

=head2 Instance Script

The instance script is used as the CGI script that manage the client's request: it is usually a very short script that just creates a new instance of your application class, and executes the process() method. This is a complete typical instance scrip...

    #!/usr/bin/perl -w
    use My::WebApp ;
    $webapp = My::WebApp->new() ;
    $webapp->process() ;

B<Note>: This script could be completely eliminated by the use of the C<Apache::CGI::Builder> extension (usable under mod_perl) which transparently executes the process.

=head2 CGI Builder Build (CBB)

This is the part of your application that implements the CBF features.

B<Note>: In this documentation we call the package that uses C::B (and that eventually includes any extension and super class) a "CGI Builder Build" or simply CBB for shortness.

The CBB is not intended to be used as a CGI script by itself, but as a class defining the methods, properties and handlers needed to integrates the CBF capability to generates the pages with your very specific needs.

Your application will inherit the CBF capability by simply using the base module CGI::Builder:

    package My::WebApp;
    use CGI::Builder;

It can inherit from more extensions or super classes including them in the 'use' statement:

    package My::WebApp;
    use CGI::Builder
    qw| CGI::Builder::SomeExtension
        My::SuperClass
        ...
      |;

B<WARNING>: B<Don't use the statement 'use base 'CGI::Builder;'>. You must just B<'use'> C::B because the CGI::Builder::import sub has to setup the overruning methods and will internally update @ISA on its own (see details in the L<"import"> advanced...

A complete CBB module is usually as simple as this one:

    package My::WebApp ;     # your class name
               
    # CBB definition
    use CGI::Builder
    qw| CGI::Builder::SomeExtension
        My::SuperClass
        ...
      |;
      
    # optional instance initialization executed for each request
    sub OH_init
    { ... }
    
    # optional Pre Process Handler executed for each request
    sub OH_pre_process
    { ... }
    
    # Switch Handler executed only when page_name is 'foo'
    sub SH_foo
    { ... }
    
    # Page Handler executed only when page_name is 'foo'
    sub PH_foo
    { ... }
    
    # Page Handler executed only when page_name is 'bar'
    sub PH_bar
    { ... }
    
    # optional Fixup Handler executed for each request
    sub OH_fixup
    { ... }