NAME
OpenInteract::Startup -- Bootstrapper that reads in modules and initializes the environment
SYNOPSIS
# Startup an OpenInteract environment outside Apache and mod_perl
use strict;
use OpenInteract::Startup;
my $R = OpenInteract::Startup->setup_static_environment(
'/home/httpd/MySite' );
# Same thing, but read the website directory from the command-line
# parameter '--website_dir' or the environment variable 'OIWEBSITE'
my $R = OpenInteract::Startup->setup_static_environment_options();
# For usage in Apache/mod_perl, see OpenInteract::ApacheStartupDESCRIPTION
This module has a number of routines that are (hopefully) independent of the OpenInteract implementation. One of its primary goals is to make it simple to initialize OpenInteract not only in a mod_perl context but also a single-use context. For example, when you create a script to be run as a cron job to do some sort of data checking (or whatever), you should not be required to put 50 lines of initialization in your script just to create the framework.
This script should also minimize the modules you have to include yourself, making it easier to add backward-compatible functionality. Most of the time, you only need to have a 'use' statement for this module which takes care of everything else.
METHODS
All methods use the class method invocation syntax, such as:
OpenInteract::Startup->require_module({ class => [ $my_class ] });main_initialize( \%params )
This will frequently be the only method you call of this class. This routine goes through a number of common steps:
read in the base configuration file
require the config class, request class and stash class
create the config object
process all packages (see process_package() below)
finalize the configuration (see finalize_configuration() below
set the config object into the stash class
create aliases in the request object (optional)
create/initialize all SPOPS object classes (optional)
The return value is a list with two members. The first is an arrayref of all SPOPS object class names that currently exist. The second is a fully setup OpenInteract::Config object. Note that his may change in the future to be a single return value of the config object with the class names included as a parameter of it.
Parameters:
You must pass in either 'base_config' or 'base_config_file'.
base_config (\%)
A hashref with the information from the base configuration file
base_config_file ($)
A filename where the base configuration can be found
alias_init (bool) (optional)
A true value will initialize aliases within the request class; the default is to not perform the initialization.
spops_init (bool) (optional)
A true value will create/initialize all SPOPS classes (see SPOPS::ClassFactory for more information); the default is to not perform the initialization.
package_extra (\@) (optional)
A list of packages not included in the filename of packages to read in but you want to include anyway (maybe you are testing a new package out). The packages included will be put at the end of the packages to be read in, although it is feasible that we break this into two extra package listings -- those to be read in before everything else (but still after 'base') and those to be read in after everything else. See if there is a need...
setup_static_environment( $website_dir, [ $superuser_password ] )
Sometimes you want to setup OI even when you are not in a web environment -- for instance, you might need to do data reporting, data import/export, or other tasks.
With this method, all you need to pass in is the root directory of your website. It will deal with everything else, including:
Reading in the server configuration
Reading in all SPOPS and action table configurations -- this includes setting up @INC properly.
Setting up all aliases -- SPOPS object and otherwise
Creating a database handle
If you pass in as the second argument a superuser password, it will create the user and check the password. If the password matches, you (and OpenInteract) will have access to the superuser object in the normal place ($R->{auth}->{user}).
If you do not wish to do this, you need to pass in a true value for 'skip_log' and 'skip_security' whenever you modify and/or retrieve objects.
Returns: A "fully-stocked" OpenInteract::Request object.
Example:
#!/usr/bin/perl
use strict;
use OpenInteract::Startup;
my $R = OpenInteract::Startup->setup_static_environment( '/home/httpd/my' );
my $news_list = eval { $R->news->fetch_group({ where => 'title like ?',
value => [ '%iraq%' ],
skip_security => 1 }) };
foreach my $news ( @{ $news_list } ) {
print "Date: $news->{posted_on}\n",
"Title: $news->{title}\n"
"Story: $news->{news_item}\n";
}Easy!
setup_static_environment_options( $usage, [ \%options ] )
Same as setup_static_environment(), but this method will try to pull the 'website_dir' parameter from the command line (using the long option '--website_dir') or if not found there the environment variable 'OIWEBSITE'.
The parameter $usage is for displaying if the 'website_dir' parameter can be found in neither.
The optional parameter \%options is for parsing additional commandline options. The keys of the hashref should be formatted in the manner Getopt::Long expects, and the values should be some type of reference (depending on the key and your intentions).
Example:
#!/usr/bin/perl
use strict;
use OpenInteract::Startup;
my $usage = "$0 --website_dir=/path/to/site --title=title";
my ( $OPT_title );
my %options = ( 'title=s' => \$OPT_title );
my $R = OpenInteract::Startup->setup_static_environment_options(
$usage, \%options );
my $news_iter = eval { $R->news->fetch_iterator({ where => 'title like ?',
value => [ "%$OPT_title%" ],
skip_security => 1 }) };
while ( my $news = $news_iter->get_next ) {
print "Date: $news->{posted_on}\n",
"Title: $news->{title}\n"
"Story: $news->{news_item}\n";
}read_package_list( \%params )
Reads in a list of packages from a file, one package per line.
Returns: arrayref of package names.
Parameters:
Choose one or the other
config (\%)
An OpenInteract::Config object which has 'package_list' as a key; this file is assumed to be in the 'config' directory, also found on the object.
filename ($)
A scalar specifying where the packages can be read from.
read_base_config( \%params )
Reads in the base configuration file, which is a simple per-line whitespace-separated key-value format.
Returns a hashref with all information.
Parameters:
filename ($)
A scalar specifying where the file is located; it must have a fully-qualified path.
dir ($)
A scalar specifying the website directory which has the file 'conf/base.conf' under it.
require_module( \%params )
Calls require on one or a number of modules. You can specify a filename composed of module names (one module per line) and all will be read in. You can also specify a number of modules to read in.
Returns: arrayref of modules successfully read in.
Parameters (choose one of the two):
filename ($)
Name of file which has modules to read in; one module per line, blank lines and lines beginning with a comment (#) are skipped
class ($ | \@)
Single classname or arrayref of classnames to read in.
process_package( \%params )
Do initial work to process a particular package. This includes reading in all external modules and reading both the action configuration and SPOPS configuration files for inclusion in the config object. We also include any modules used in the action definition (if you specify a 'class' in a action definition) as well as those in the 'isa' property of a SPOPS class definition.
We also add the package directory to @INC, which means any 'use' or 'require' statements that need modules within the package will be able to work. (See the OpenInteract Guide to Packages for more information on what goes into a package and how it is laid out.)
Note that we do not create/configure the SPOPS classes yet, since that process requires that all SPOPS classes to be used exist in the configuration. (See SPOPS::ClassFactory for more details.)
Parameters:
package ($)
Name of package to be processed; this should correspond to a particular directory in the package directory
config (obj)
An OpenInteract::Config object or hashref with configuration information.
package_dir (\@) (optional)
Directories where this package might be kept; if not passed in, it will be found from the config object
read_action_definition( \%params )
Read in a action definition file (a perl data structure) and set its information in the config object. Multiple actions can be configured, and we do a 'require' on any actions referenced.
Parameters:
filename ($)
File where the action definion is.
config (obj)
OpenInteract::Config object where we set the action information.
package (\%)
Hashref with information about a package so we can set name/version info.
read_spops_definition( \%params )
Read in a module definition file (a perl data structure) and set its information in the config object. Multiple SPOPS objects can be configured, and we do a 'require' on any modules referenced.
Parameters:
filename ($)
File where the module definion is.
config (obj)
OpenInteract::Config object where we set the module information.
package (obj)
Hashref with information about a package so we can set name/version info.
read_perl_file( \%params )
Simple routine to read in a file generated by or compatible with a perl data structure and return its value. For instance, your file could have something like the following:
$action = {
'boxes' => {
'class' => 'OpenInteract::Handler::Boxes',
'security' => 'no',
}, ...
};And the return value would be the hashref that $module is set to. The actual name of the variable is irrelevant, just the data structure assigned to it.
Return value is the data structure in the file, or undef if the file does not exist or the data structure is formatted incorrectly. If the latter happens, check your error log (STDERR) and a warning will appear.
Parameters:
filename ($)
File to read data structure from.
Note: we should modify this to use SPOPS::HashFile...
finalize_configuration( \%params )
At this point, all the SPOPS and module information should be read into the configuration object and we are ready to finish up the configuration procedure. This means call the final SPOPS configuration, which creates classes as necessary and puts configuration information and routines to link the objects together. We also call the various routines in the 'request_class' (usually OpenInteract::Request) to create necessary aliases for classes from both SPOPS and base system elements.
Return value is an arrayref of all SPOPS classes that are configured. Each one needs to be initialized before use, which can handily be done for you in the initialize_spops method.
Parameters:
config (obj)
An OpenInteract::Config configuration object. Note that the keys 'request_class' and 'stash_class' must be defined in the config object prior to calling this routine.
initialize_spops( \%params )
Call the class_initialize method for each of the SPOPS classes specified. This must be done before the package can be used.
Returns an arrayref of classes successfully initialized.
Parameters:
class (\@)
An arrayref of classes to initialize.
config (obj)
An OpenInteract::Config configuration object, needed by the
class_initializemethod within the SPOPS classes.
TO DO
Find common code with SPOPS::Initialize
SPOPS::Initialize is new in version 0.40 and contains common code for initializing SPOPS object classes. We should be able to use it to perform some of our actions.
BUGS
None known.
COPYRIGHT
Copyright (c) 2001-2002 intes.net, inc.. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHORS
Chris Winters chris@cwinters.com