- NAME
- OVERVIEW
- GETTING TO $R
- RELATIONSHIP WITH THE STASH CLASS
- METHODS RETURNING OBJECT OR CLASS NAME
- ACTION METHODS
- HASH KEY PROPERTIES
- ALIASES FOR METHODS DONE ELSEWHERE
- GLOBAL INFORMATION
- AUTHORS

# NAME

OpenInteract::Request - Description and Contents of $R

# OVERVIEW

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:

- The Apache request (or Apache::Request) object

- A DBI database handle

- Configuration object

- Caching object/class

- Template object

- Error handler listings

- Anything else you can think of.

You can also determine which class and method a module uses and find out what the class name of different SPOPS objects are.

# GETTING TO $R

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.

# RELATIONSHIP WITH THE STASH CLASS

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.

# METHODS RETURNING OBJECT OR CLASS NAME

All of the following are actually kept within a lexical variable in the stash class.

- $R->db

  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 );

- $R->config

  Returns config object (or maybe just hashref)

       my $db_info = $R->config->{service}->{database}->{main};

- $R->cache

  Returns cache class name, suitable for adding, clearing, checking, etc. [[ NOTE: Currently non-functional ]]

       my $rv = $R->cache->add( id => $id, item => $obj );

- $R->apache

  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 );
       }

- $R->uri

  Returns Apache::URI object

       my @path_items = split /\//, $R->uri->path();

- $R->error

  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.

- $R->session

  Returns the class name of module that creates/saves sessions

       $R->session->parse_handler;

- $R->cookies

  Returns the class name of module that parses/sends cookies

       $R->cookie->parse_handler;

# ACTION METHODS

- $R->lookup_conductor( [ $module_alias ] )

  Finds out what conductor needs to be called given a particular module.

- $R->lookup_module( [ $module_alias ] )

  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();

- $R->scrib( $level, $message [, $message, ... ] )

  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.)

# HASH KEY PROPERTIES

- $R->{templates_used}

  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.

- $R->{auth}->{logged_in}

  True if the user is logged in, false if not.

- $R->{auth}->{user}

  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}";
       }

- $R->{auth}->{group}

  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}";
       }

- $R->{theme}

  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";
       }

- $R->{session}->{ $key }

  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.";

- $R->{cookie}->{in}->{ $key }

  Returns the information for the incoming cookie specified by $key.

       my $session_id = $R->{cookie}->{in}->{session_id};

- $R->{cookie}->{out}->{ $key }

  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' } );

- $R->{time}

  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} );

- $R->{boxes}

  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.

# ALIASES FOR METHODS DONE ELSEWHERE

- $R->throw

  Alias for $R->error->throw, which throws an error and calls a particular error handler, depending on the type of error you've raised.

# GLOBAL INFORMATION

If your handler is a subclass of `OpenInteract::SPOPS`, you don't need to instantiate $R for a number of commonly used items.

- global_user_current;

  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";

- global_group_current;

  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}";
       }

- global_user_class

  Returns the class used to manipulate user objects.

       my $user = $class->global_user_class->fetch_by_username( $username );

- global_group_class

  Returns the class used to manipulate group objects.

       my $group = $class->global_group_class->fetch( $gid );

- global_error_class

  Returns the class to use when we throw an error.

       my $error_class = $class->global_error_class;
       $error_class->throw( { code => 192, type => 'db' ... } );

- global_cache_class

  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;

- global_config

  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' );

- global_db_handle

  Returns the database handle associated with this request.

       my $quoted_value = $R->db->quote( "this_value's information" );

- global_secure_class

  Returns the SPOPS class that deals with security, generally `SPOPS::Secure`.

       my $secure_class = $class->global_secure_class;
       my $level = $secure_class->check_security( { ... } );

- global_security_object_class

  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, { ... } );

# AUTHORS

Chris Winters <chris@cwinters.com>