view release on metacpan or  search on metacpan

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

=head1 NAME

CGI::Builder::CgiAppAPI - Use CGI::Application API with CGI::Builder

=head1 VERSION 1.27

The latest versions changes are reported in the F<Changes> file in this distribution. To have the complete list of all the extensions of the CBF, see L<CGI::Builder/"Extensions List">

=head1 INSTALLATION

=over

=item Prerequisites

    CGI::Builder >= 1.3
    

=item CPAN

    perl -MCPAN -e 'install CGI::Builder::CgiAppAPI'

You have also the possibility to use the Bundle to install all the extensions and prerequisites of the CBF in just one step. Please, notice that the Bundle will install A LOT of modules that you might not need, so use it specially if you want to exte...

    perl -MCPAN -e 'install Bundle::CGI::Builder::Complete'

=item Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install

=back

=head1 SYNOPSIS

   # In your old cgiapp implementation
   # change the follow line
   # use base qw( CGI::Application ) ; # or 'CGI::Application::Plus'
   
   # with this (to use the same cgiapp under CBF)
   use CGI::Builder
   qw| CGI::Builder::CgiAppAPI
     |;
   
   # this will provide you useful hints
   $CGI::Builder::CgiAppAPI::hints = 1 ;
   
   # when your migration is completed
   # just get rid of the CGI::Builder::CgiAppAPI
   use CGI::Builder ;
   

=head1 DESCRIPTION

B<Note>: You should know L<CGI::Builder>.

This module supplies an API compatible with the C<CGI::Application> or C<CGI::Application::Plus> APIs. It transparently provides all the aliases, defaults and method redefinition to make the old cgiapps work unchanged under CBF as well. Besides, it p...

B<WARNING>: This module is not intended to be used neither as an alternative API for the CBF nor in a production environment. You should use it only as:

=over

=item *

the glue-code to add new CBF methods and capability to your old cgiapps, thus temporarily running applications implementing mixed APIs

=item *

a substantial aid to the migration process from an old cgiapp to the CBF

=item *

a startup aid to learn (faster) the CBF API (just if you are familiar with the cgiapp API)

=back

B<IMPORTANT>: This API is compatible with the CGI::Application 3.1. The API of successive CGI::Application versions may or may not work as well; I have no plan to update this module to maintain API compatibility.

=head1 LEARNING WITH THIS API

If you are familiar with cgiapp API, you can use this module as an aid to quickly learn how to change your 'cgiapp abits'. Just build your application including it, and switch the hints ON:

   # define your build
   use CGI::Builder
   qw| CGI::Builder::CgiAppAPI
     |;
   
   # switch the hints ON
   $CGI::Builder::CgiAppAPI::hints = 1 ;

Then start to code as you already know (i.e. use the old cgiapp API), and run your code as soon as it is ready to be tried. You will receive the warnings that will 'teach' you the new API, and will suggest you what to change and what to read in the d...

When you have learned enough, just get rid of this module, and use the CBF API alone.

=head1 MIGRATING

=head2 Step by step instructions

=over

=item 1 Define the CBB including this API

As the first step just change the old dependency with the new one. For example:

    # take off this statement
    use base qw(CGI::Application);
    
    # and substitute it with the following one
    use CGI::Builder
    qw| CGI::Builder::CgiAppAPI
      |;

These are all the possible configurations for all the possible modules covered by this API. Use the one that apply:

=over

=item CGI::Application

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

    { do_something_useful }
    
    # check if exists a parameter
    exists $s->param->{myPar} ;
    
    # delete a parameter
    delete $s->param->{myPar} ;

In list context the param() returns a copy of the parameter hash.

=head1 API CONVERSION TABLE (quick reference)

    CGI::Application[::Plus]      CGI::Builder
    ========================      ============
    mode_param [default:'rm']     cgi_page_param [default:'p']
    start_mode [default:'start']  page_name  [default:'index']
    get_current_runmode           page_name
    QUERY                         cgi
    query                         cgi
    cgiapp_get_query              cgi_new
    PARAMS                        param
    TMPL_PATH                     page_path
    tmpl_path                     page_path
    prerun_mode                   switch_to
    header_prop                   header
    header_add                    header
    header_type                   redirect | dont_send_header | -
    run_modes                     page_handler_map
    run                           process
    cgiapp_init                   OH_init
    startup                       OH_init
    cgiapp_prerun                 OH_pre_process
    cgiapp_postrun                OH_fixup
    teardown                      OH_cleanup
    dump                          CGI::Builder::Test::dump
    dump_html                     CGI::Builder::Test::dump_html
    load_tmpl                     - | CGI::Builder::HTMLtmpl
    $ENV{CGI_APP_RETURN_ONLY}     capture('process')

    CGI::Application::Plus        CGI::Builder
    ======================        ============
    runmode [default:'start']     page_name [default:'index']
    RM_prefix [default:'RM_']     'PH_' (constant value)
    page                          page_content
    start_capture                 capture
    stop_capture                  capture
    qparam                        --

=head1 CHANGES

The CBF implements a different metaphor based on 'processing pages' instead of 'running applications'. This should be simpler to understand (specially for beginners) because it is more consistent with the specific task that a CGI::Builder application...

Even if the internal implementation of similar methods is greatly improved and has a completely different internal code, from the user point of view most changes here don't require more than a simple translation of identifier from one concept to the ...

The CGI::Application philosophy is very simple: the application defines several run methods, and each run method is organized to produce and return its own output page. You have to set a map in the application to define what run method has to be call...

The CBF let you organize your application in a far more flexible way, it just need to find some C<page_content> to send to the client: it does not matter what method or handler has set it during the process, (and the C<page_content> itself might even...

This flexible structure open several handy and powerful possibilities to your application and to the extension system. If you want to know some more details about that, you could read L<CGI::Application::Plus/"Exclusive Features and Improvements"> wh...

B<Note>: The changes reported below are needed just if you want to completely convert your old cgiapp to the CBF. Until you include this API in your build, they are transparently added to your application.

=head2 mode_param

Change it with C<cgi_page_param>.

C<mode_param> is used to define the query parameter that holds the run mode, and its default is 'rm'. The CGI::Builder property to use is the C<cgi_page_param> and its default is 'p', so if your old cgiapp rely on the default, you should either set e...

    # (simpler) solution 1: put this line in the OH_init()
    $s->cgi_page_param = 'rm';
    
    # solution 2: change the links like: '/webapp.cgi?rm=myRunmode'
    # to '/webapp.cgi?p=myRunmode'

Besides, the old C<mode_param> accepted as well a CODE reference returning the page name, while C<cgi_page_param> doesn't. In this case - if you want to generate the page name by some sub - you should just override the C<get_page_name()> method, and ...

    sub get_page_name {
        my $s= shift;
        ... your code to get the page name ...
        $s->page_name = $resulting_page_name
    }

=head2 start_mode, get_current_runmode, runmode

Change them with C<page_name> (i.e. the cgiapp runmode).

C<start_mode>, C<get_current_runmode> (and C<runmode> in CGI::Application::Plus) are used to set and get the (start) run mode (i.e. the CGI::Builder page name). You should use the C<page_name> property instead.

    $s->page_name = 'mystart'
    $s->page_name  # always returns the current page name

B<Important Note>: Remember that the default C<page_name> is 'index' while the default run mode was 'start' so if you get rid of this API after a migration you should consider this new default.

=head2 QUERY and query

Change them with C<cgi>.

C<QUERY> (and C<query> in CGI::Application::Plus) are used to pass a cgi object with the C<new()> method. You should use C<cgi> property instead.

    $webapp = WebApp->new(cgi=>CGI->new) ;
    # or
    $s->cgi = CGI->new ;

=head2 cgiapp_get_query

Just change it with C<cgi_new>.

=head2 PARAMS

Change them with C<param>.

C<PARAMS> is used to pass a reference to an hash containing some param with the C<new()> method or to set some application param. The CBF accessor to set and retrieve your application param is the C<param()> property group accessor, you should use it...

=head2 TMPL_PATH and tmpl_path

Change them with C<page_path>.

C<TMPL_PATH> (and C<tmpl_path> in CGI::Application::Plus) are used to pass a template path with the C<new()> method. You should use C<page_path> property instead

    $webapp = WebApp->new(page_path=>'/mypath')