view release on metacpan or  search on metacpan

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

You can use this handlers to do something specific for different pages, such as e.g. executing some specific code just for that specific request (or creating the specific page content when your handler don't use any automagic template integration)

=head3 PH_AUTOLOAD

This is a special Page Handler which will be called IF defined and IF there are no other defined page handler for the specific requested page and UNLESS the page_content_check() return true (i.e. there is no page content so far).

The main purpose of this handler is giving you one more option to generate the page_content if no other handler has generated it so far, so you can use it e.g. as the last chance to redirect the client or switch_to your special 'Not found' page durin...

You can also use the C<page_handler_map> advanced accessor to map the AUTOLOAD handler to any method you prefer.

B<Note>: The execution of this handler is skipped by the presence of:

=over

=item *

any specific PH handler defined for the current page

=item *

any page_content already defined

=item *

a found template, which is supposed to generate the page content if you use any template integration Extension

=back

If you need a wider solution you should use an C<OH_pre_page> or an C<OH_fixup> handler instead, which get always called without any restriction.

=head1 ADVANCED FEATURES

In this section you can find all the most advanced or less used features that document all the details of the CBF. In most cases you don't need to use them, anyway, knowing them will not hurt.

=head2 CONSTANTS

These constant are used to set and check the Process Phase. They return just a progressive integer:

  CB_INIT         0
  GET_PAGE        1
  PRE_PROCESS     2
  SWITCH_HANDLER  3
  PRE_PAGE        4
  PAGE_HANDLER    5
  FIXUP           6
  RESPONSE        7
  REDIR           8
  CLEANUP         9

=head2 Global Variables Persistence

If you are using mod_perl, you should know the "Global Variables Persistence" issue: this is something that you must consider when your CBB is running under mod_perl, even when your CBB doesn't use Apache::CGI::Builder.

More explicitly you should know that the CBF and its extensions may use Global Variables to store certain data which are B<class scoped> (i.e. used for all the processes of your CBB class), thus caching the data and saving some processing.

The Global Variables that the CBF uses are always accessed by an OOTool accessor, they are just B<Class Accessors> instead of B<Object Accessors>: the behaviour of a Class accessors (property or group) is the same, but the underlaying accessed variab...

Examples of Class Accessors are the L<"Class Property Group Accessors"> of this module, or the C<tm>, C<tm_new_args> and C<tm_lookups_package> accessors of the CGI::Builder::Magic extension (which creates the Template::Magic object just once -the fir...

B<Note>: You should clearly distinguish the B<class accessors> among the others because this particular feature is usually written in B<bold> at the start of the accessor doc.

=head2 Advanced Methods

=head3 capture( CODE )

This method executes the I<CODE> (which can be a method name or a CODE ref) and returns a ref to the captured output, so allowing you to eventually test your sub classes, or doing something with the output (e.g. in a OH_fixup() when the page content ...

  $captured_output = $webapp->capture('process');
  if ( $$captured_output =~ /something to test/ ){
      print 'ÍT WORKS!'
  }

  sub OH_fixup {
      my $s = shift ;
      if (ref $s->page_content eq 'CODE')  {
          # executes the referenced CODE and capture the output
          $s->page_content = $s->capture($s->page_content)
      }
      # do something with $s->page_content as usual
  }

=head3 phase( [phase_number] )

This method returs the current phase name or the name of the passed I<phase_number> argument.

=head2 Internal Methods

B<You don't need to directly use any of these methods because they are used internally> but you might need to override them in very special cases, so they are documented here.

=head3 get_page_name

Used internally to set the C<page_name> to the value of the C<cgi_page_param> query parameter at the very start of the process. (e.g. this query parameter ?p=myPage will set the C<page_name> to 'myPage')

If you don't want to pass the page parameter as a query parameter, or if you have any other custom need you can override this method which should set the C<page_name> as you need.

=head3 send_header

Used internally to send the C<header> to the client.

This accessor is backed by the C<header()> CGI function, so IF (and only if) you implement a different query object not based on CGI.pm, AND the object you use 'can' not "header", THEN you cannot use this method, so you need to override it.

=head3 send_content

Used internally to send the C<page_content> to the client.

=head3 AUTOLOAD

This method (not to be confused with the 'PH_AUTOLOAD' Page Handler) implements an handy param accessor. You can store or retrieve some param as it was an object property:

    # instead of do this
    $s->param(my_Param => 'some init value')
    
    # you can do this directly
    $s->my_Param = 'some init value' ;
    
    # same thing with the new() method
    $webapp = WebApp->new(my_Param => 'some init value')
    
    # or with the explicit assignation
    $webapp = WebApp->new(param => {my_Param      => 'some init value',