Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

ModPerl::ParamBuilder
Makes building custom Apache directives easy

ModPerl::ParamBuilder - Makes building custom Apache directives easy


NAME

ModPerl::ParamBuilder - Makes building custom Apache directives easy


SYNOPSIS


   package MyApp::Parameters;

   use ModPerl::ParamBuilder;

   use base qw( 'ModPerl::ParamBuilder' );

   my $builder = ModPerl::ParamBuilder->new( __PACKAGE__ );

   # Build simple one argument parameter

   $builder->param( 'Template'     );

   $builder->param( 'PageTitle'    );

   $builder->param( 'ItemsPerPage' );

   # Build an On/Off parameter

   $builder->on_off( 'Caching'     );

   # Build a Yes/No parameter 

   $builder->yes_no( 'AutoCommit'  );

   # Build a no argument/flag parameter

   $builder->no_arg( 'Active'      );

   # Build a one argument parameter with a custom error message

   # and special configuration hash key 

   $builder->param( {

                        name    => 'SMTPServer',

                        err     => 'SMTPServer xx.xx.xx.xx',

                        key     => 'smtp_server',

                    });

   # Load the configuration into Apache 

   $builder->load;

   ################################################

   # And elsewhere in your application

   ################################################

   package MyApp::Main;

   # Retrieve the configuration like so

   my $params   = MyApp::Parameters->new; 

   my $conf_ref = $params->get_config( $r ); 

  

   # Or if you have PerlOptions +GlobalRequest on then you can just

   # call 

   my $conf_ref = $params->get_config;


DESCRIPTION

One of the neatest features of mod_perl 2.0 is the ability to easily create your own custom Apache directives. Not only are they more efficient to use compared to PerlSetEnv, PerlPassEnv, PerlAddVar, and PerlSetVar, but they give your application a more polished and professional look and feel..

Not to mention they're just plain cool. This module aims to make the already easy, even easier.

Note that you MUST load your parameter module with PerlLoadModule in your httpd.conf and not PerlModule. This is necessary because Apache needs to load your module earlier than usual in the startup to be able to read it's own configuration now.


METHODS

new


    package MyApp::Params;

    use base qw( ModPerl::ParamBuilder );

    my $builder = ModPerl::ParamBuilder->new( __PACKAGE__ );

This function creates a new ParamBuilder object. You must pass either the name of your application's parameter module or use the handy __PACKAGE__ built in.

param

This function is used to build the more general directives. To create a simple directive named Foo that takes one argument you simply call:


   $builder->param( 'Foo' );

Assuming you put your directives in MyApp::Parameters, you can then use Foo in Apache httpd.conf like so:


   PerlLoadModule MyApp::Parameters

   <Location /myapp> 

      SetHandler perl-script 

      Foo Bar 

      PerlResponseHandler MyApp::Main 

   </Location>

When you retrieve the configuration with get_config() Foo's argument will be stored in the hash key of the same name ( i.e. 'Foo' ).

param() can also take a hash of options that give you more access to using some more advanced features of Apache directives. The valid options are:


    name -- Name of the directive used in httpd.conf 

    key  -- Hash key to store this directives arguments in 

    err  -- Custom error message used with this directive 

    func -- Custom function used to process the directives on Apache 

            startup. See the mod_perl 2.0 documentation for more 

            information on how to use a custom function for 

            processing and/or validating the arguments 

    take -- How many arguments to take and which are required, etc.

For example, if you wanted to create a directive named SMTPServers that took an arbitrarily long list of IP addresses of SMTP server your application should use, and you wanted it to be stored in the configuration as 'smtp_servers', it can be built like this:


   $builder->param({

                      name    => 'SMTPServers',

                      key     => 'smtp_servers',

                      err     => 'SMTPServers xx.xx.xx.xx yy.yy.yy.yy', 

                      take    => 'list',

   });

This list of SMTP servers can then be retrieved like so:


   my $conf_ref = MyApp::Parameters->get_config;

   my @smtp_servers = $$conf_ref{smtp_servers};

Because ModPerl::ParamBuilder will return a list to you in this case rather than a single value.

The valid options for take are:


 1    or one          -- Take one argument (default)

 2    or two          -- Take two arguments 

 3    or three        -- Take three arguments 

 12   or one_plus     -- One mandatory argument  with one optional 

 23   or two_plus     -- Two mandatory arguments with an optional third

 123  or one_plus_two -- One mandatory argument  with two optional ones

 list                 -- An arbitrarily long list of arguments 

 one_plus_list        -- One mandatory argument followed by an 

                         arbitrarily long list of additional 

                         arguments

no_arg( $name )

This allows you to define an Apache directive which takes no arguments. Each time this value is used the value in the configuration hash will be incremented. The value in the hash for the key $name will be undefined if it does not appear in httpd.conf

yes_no( $name )

This creates a simple Yes or No directive. The value in the configuration hash will be 1 ( Yes ) or 0 ( No ) depending on the definition in httpd.conf

on_off( $name )

This creates a simple On or Off directive. The value in the configuration hash will be 1 ( On ) or 0 ( No ), just like yes_no().


LIMITATIONS

The biggest limitation is that this module ONLY works with mod_perl 2.0 and above. There are no plans to support mod_perl 1.x for this module, trust me you want to upgrade to mod_perl 2 as soon as you can.

This module's intent is not to replace the underlying mod_perl APIs nor is it intended to be used for complicated cases where special processing is needed. It is intended to make the simple things simple.

Some things to keep in mind when using ModPerl::ParamBuilder

This module does not restrict where the directives can be used in Apache's httpd.conf. To restrict directives to particular area ( only in main server conf, a VirtualHost, or a Location, etc ) you will need to use the mod_perl APIs to build your directives.

This also does not do, by default, any error checking or validation on the arguments passed to directives. If you create a directive 'NumberOfItemsPerPage' and then put:


     NumberOfItemsPerPage rhubarb

Apache will not see this as an error and your configuration hash for the key 'NumberOfItemsPerPage' will contain the string 'rhubarb'. You can validate this data in three different ways:


    1) Validate the configuration data in your application prior to

       using it.

    2) Instruct ModPerl::ParamBuilder to use a special function for

       processing the arguments by passing the 'func' option.

    3) Revert to using the mod_perl API where you have more control.

See the appropriate mod_perl 2.0 API modules for how to accomplish more in depth processing of directives and their data.


BUGS

None that I am aware of. Please report any you find to the E-mail address below.


SEE ALSO

Apache2::Module(3), Apache2::CmdParms(3), the examples/ directory of this module, and the mod_perl 2.0 documentation.


AUTHOR

Frank Wiles <frank@revsys.com> http://www.revsys.com/


COPYRIGHT

Revolution Systems, LLC. All rights reserved.


LICENSE

This software can be distributed under the same terms as Perl itself.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy