| Home | Wiki | OI 1.x Docs | OI 2.x Docs |
|
OpenInteract::Request - Description and Contents of $R
The variable $R is the framework's request object. It acts as a container for other objects, repository for aliases all over the system and a place to call methods that deal with actions based on the configuration.
Some objects retrievable through $R:
You can also determine which class and method a module uses and find out what the class name of different SPOPS objects are.
The $R variable is always present, one per Apache child. It gets
cleaned up after every request, so there should be no memory leakage
issues. We can do this because class for $R (OpenInteract::Request) is a
subclass of Class::Singleton. This allows us to create the object once
and have it always ``be there'' when we ask for it.
To ask for it, we simply need to do this:
my $R = OpenInteract::Request->instance;
We can do this in any handler, in any object definition class or any utility class. If you like, you can include the OpenInteract::Request class specifically in your module, but it is not necessary.
The 'stash class' must be implmented on a per-application basis. Even
though you can reach all the classes/objects through $R, $R actually
passes off the request to the stash class, which is defined in the
base configuration of your website (conf/base.conf).
We do this because you might want to run more than one application or website under the OpenInteract framework. It is feasible to do so by running each application self-contained, by running the mod_perl processes on a nonstandard port number and using a proxy scheme to pass requests back to the right set of processes. But this is wasteful.
Instead, we need to ensure that all application-specific information is kept in one place, and that $R knows how to get to it. Well, it does, so you don't have to worry about it.
All of the following are actually kept within a lexical variable in the stash class.
Returns DBI database handle. Most of the time you won't have to deal with this since SPOPS does the work behind the scenes, but it's useful to know it's there.
my $sth = $R->db->prepare( $sql );
Returns config object (or maybe just hashref)
my $db_info = $R->config->{service}->{database}->{main};
Returns cache class name, suitable for adding, clearing, checking, etc. [[ NOTE: Currently non-functional ]]
my $rv = $R->cache->add( id => $id, item => $obj );
Returns Apache (or Apache::Request) object
$R->apache->send_http_header();
my $apr = $R->apache;
foreach my $field ( $apr->param ) {
$info->{ $field } = $apr->param( $field );
}
Returns Apache::URI object
my @path_items = split /\//, $R->uri->path();
Returns class name of error object.
$R->error->throw( { code => 404, user_msg => 'la la la' ... });
or:
my $error_class = $R->error;
$error_class->throw( { code => 404, ... } );
$error_class->throw( { code => 505, ... } );
Note that throw() is also an alias directly from $R. See below.
Returns the class name of module that creates/saves sessions
$R->session->parse_handler;
Returns the class name of module that parses/sends cookies
$R->cookie->parse_handler;
Finds out what conductor needs to be called given a particular module.
Returns class name and method of next module in sequence (if no alias given) or the module class and method corresponding to $module_alias
my ( $class, $method ) = $R->lookup_module; my $html = $class->$method();
Logs the $message at $level, which will go to wherever you have configured logging for that level to go.
(Note: not configured yet; not certain we need to do so.)
Contains a queue (most recent at the head) of template objects used in the current request.
$R->{main_template_vars}
Contains a hashref of variables to use when we process the main template. Any of the components can add to this during their processing phase.
True if the user is logged in, false if not.
Contains the authenticated user. If the user is not logged in, currently it's empty but it will contain the 'not-logged-in' user in the near future. The {logged_in} property tells you whether the user is logged in or not.
if ( my $u = $R->{auth}->{user} ) {
print "Hi there $u->{first_name} $u->{last_name}";
}
If there is a valid entry in $R->{auth}->{user}, then the list of groups the user if a member of will be here
foreach my $group ( @{ $R->{auth}->{group} } ) {
print "You are a member of group: $group->{name}";
}
The object representing the theme to be used for the current request. This should always be defined.
my $props = $R->{theme}->all_values;
print "Properties used in this theme:\n";
foreach my $prop ( keys %{ $props } ) {
print " -- $prop: $props->{ $prop}\n";
}
Allows you to retrieve or set information for a particular session $key. The session_id can be retrieved from the {_session_id} key.
$R->{session}->{shopping_items}++;
my $ssn_id = $R->{session}->{_session_id};
print "You have ", $R->{session}->{shopping_items},
" in your cart.";
Returns the information for the incoming cookie specified by $key.
my $session_id = $R->{cookie}->{in}->{session_id};
Set/retrieve information for the outgoing cookie specified by
$key. Note that the create_cookie method knows whether you are
using the CGI module or the Apache::Cookie module for cookie
parsing/creating.
$R->cookie->create_cookie( { name => 'mycookie', value => $my_calue,
path => '/', expires => '+3M' } );
Time this request was started, in number of seconds since the epoch format. You can get a more inteligible format by using this value in combination with the localtime function.
print "Request started at ", scalar localtime( $R->{time} );
Components to be used for boxes that the handlers can control. For instance, if I'm in the 'contact' tool, I might want to have the 'contact_tool_box' box be displayed. So all I do is:
push @{ $R->{boxes} }, 'contact_tool_box';
And it will be displayed at the right time. Note that order is important.
Alias for $R->error->throw, which throws an error and calls a particular error handler, depending on the type of error you've raised.
If your handler is a subclass of OpenInteract::SPOPS, you don't
need to instantiate $R for a number of commonly used items.
Returns the object corresponding to the user who is executing this request.
my $user = $class->global_user_current;
warn " User: $user->{first_name} $user->{last_name}\n";
Returns a list of groups that the current user belongs to. If there is no current user (e.g., the user has not logged in), this will be undef,
my $group_list = $class->global_group_current || [];
foreach my $group ( @{ $group_list } ) {
print "You are a member of group: $group->{name}";
}
Returns the class used to manipulate user objects.
my $user = $class->global_user_class->fetch_by_username( $username );
Returns the class used to manipulate group objects.
my $group = $class->global_group_class->fetch( $gid );
Returns the class to use when we throw an error.
my $error_class = $class->global_error_class;
$error_class->throw( { code => 192, type => 'db' ... } );
Returns the class we use to cache objects, text, etc.
my $cache_class = $class->global_cache_class;
my $html = $cache_class->get( 'mykey' );
if ( ! $html ) {
... generate html ...
}
return $html;
Returns the configuration object -- basically a hashref with a few
methods attached. (See OpenInteract::Config.)
my $conf = $class->global_config; print "Template Directory: ", $conf->get_dir( 'template' );
Returns the database handle associated with this request.
my $quoted_value = $R->db->quote( "this_value's information" );
Returns the SPOPS class that deals with security, generally
SPOPS::Secure.
my $secure_class = $class->global_secure_class;
my $level = $secure_class->check_security( { ... } );
Returns the SPOPS (or other) class that implements security objects in
the system; this is always implemented in the base_security
package.
my $sec_obj_class = $class->global_security_object_class;
my $obj = $sec_obj_class->fetch_match( $class, { ... } );
Chris Winters <chris@cwinters.com>