/ 
OpenInteract-1.99_03
River stage zero No dependents
/ OpenInteract2::Request

NAME

OpenInteract2::Request - Represent a single request

SYNOPSIS

# In server startup/OI::Context initialization
 
OpenInteract2::Request->set_implementation_type( 'cgi' );

# Later...
use OpenInteract2::Request;

my $req = OpenInteract2::Request->get_current;
# also:
my $req = CTX->request;
print "All parameters: ", join( ', ', $req->param(), "\n";
print "User agent: ", $req->user_agent(), "\n";

DESCRIPTION

This object represents all information that we know about a request. It is modeled after the interfaces for CGI and Apache::Request, so there are a couple of items that are slightly inconsistent with the rest of OpenInteract.

When you create a new request object you need to specify what type of request it is. (Your OpenInteract server configuration should have this specified in the 'context_info' section.) The process of initializing the object during the new() call fills the Request object with any parameters, uploaded files and important headers from the client.

The OpenInteract2::Context object is responsible for associating cookies and the session with this request object.

METHODS

Class Methods

set_implementation_type( $type )

get_implementation_type()

new( @params )

Parameters

param( [ $name, $value ] )

With no arguments, this returns a list -- not an arrayref! -- of parameters the client passed in.

If you pass in $name by itself then you get the value(s) associated with it. If $name has not been previously set you get an empty list or undef depending on the context. Otherwise, we return the context-sensitive value of $name

If you pass in a $value along with $name then it's assigned to $name, overwriting whatever may have been there before.

Returns: list of parameters (no argument), the parameter associated with the first argument (one argument, two arguments),

param_toggled( $name )

Given the name of a parameter, return 'yes' if it's defined and 'no' if not.

param_date( $name, [ $strptime_format ] )

Given the name of a parameter return a DateTime object populated with the data input from the HTTP request.

The parameter $name can refer to:

  1. a single field, in which case you must specify a strptime format in $format

  2. multiple fields where $name is a prefix and '_year', '_month', '_day' are the suffixes.

For example:

# mydate = '2003-04-01'
my $datetime = $request->param_date( 'mydate', '%Y-%m-%d' );

# mydate_year  = '2003'
# mydate_month = '04'
# mydate_day   = '01'
my $datetime = $request->param_date( 'mydate' );

If you specify a format and the parser cannot parse the date you give with that format an exception will be thrown.

param_datetime( $name, [ $format ] )

Similar to param_date in that it reads parameter information and returns a DateTime object, except it also reads hour, minute and AM/PM information.

The parameter $name can refer to:

  1. a single field, in which case you must specify a strptime format in $format

  2. multiple fields where $name is a prefix and '_year', '_month', '_day', '_hour', '_minute' and '_am_pm' are the suffixes.

For example:

# mytime = '2003-04-01 6:08 PM'
my $datetime = $request->param_date( 'mytime', '%Y-%m-%d %I:%M %p' );

# mytime_year   = '2003'
# mytime_month  = '04'
# mytime_day    = '01'
# mytime_hour   = '6'
# mytime_minute = '08'
# mytime_am_pm  = 'PM'
my $datetime = $request->param_datetime( 'mytime' );

If you specify a format and the parser cannot parse the date you give with that format an exception will be thrown.

Request URL

assign_request_url( $full_url_path )

This method is normally only called by the implementing subclass. The subclass should pass the full, absolute URL path (no protocol, host or port) so the url_absolute and url_relative properties are properly set. This also sets the action name and task for use by the controller.

If you want to do any behind-the-scenes redirection before the OpenInteract2::Controller is instantiated, you can pass a path to this and the correct action will be processed. For instance, you can configure your site to force users to login, so no matter what URL is requested by a user who isn't logged in they'll always get your login page. This is done in the OpenInteract2::Auth class -- if the user isn't logged in it assigns a new request URL which changes the action processed by the controller.

Incoming Cookies

cookie( [ $name, $value ] )

With no arguments it returns a list -- not an arrayref! -- of cookie names the client passed in.

If you pass in $name by itself you get the value associated with the cookie. This is a simple scalar, not a CGI::Cookie object.

If you pass in a $value along with $name then it's assigned to $name, overwriting whatever may have been there before.

Note: These are only incoming cookies, those the client sends to the server. For outgoing cookies (setting cookies on the client from the server) see OpenInteract2::Response.

Returns: list of cookie names (no argument), the value associated with the first argument (one argument, two arguments).

Incoming Uploads

upload( [ $name ] )

With no arguments, this returns a list -- not an arrayref! -- of OpenInteract2::Request::Upload objects mapping to the files uploaded by the client. If you pass in $name then you get the specific OpenInteract2::Request::Upload object associated with it.

Returns: list of parameters (no argument), or the parameter associated with the single argument.

clean_uploads()

Deletes all uploads associated with the request.

Properties

url_absolute

This is set to the URL the user entered, still containing the deployment context.

url_relative

This is set to the internal URL OI uses. It does not include the deployment context. It should be the URL all actions deal with.

url_initial

This is the URL we used to lookup the action.

theme

Theme object associated with this request. May change if user is logged in and has different theme.

theme_values (read-only)

Hashref (not an object) of flattened theme properties. This is set automatically when theme property is set.

session

The current user's stateful session.

action_name

Name of the action as gleaned from the URL. (May be empty, may change as a result of lookups.)

task_name

Task of the action as gleaned from the URL. (May be empty, may change as a result of lookups.)

auth_user

User logged in (or not) for this request. This should always be filled with a user object, even if it's the 'not-logged-in' user.

auth_group

Groups current user belongs to. May be empty.

auth_is_admin

True if current user is an administrator, false if not. (You can customize this: see OpenInteract2::Auth::AdminCheck).

auth_is_logged_in

True if current user is a legitimate user, false if it's the 'not-logged-in' user.

auth_user_id

Shortcut so you do not have to test whether the user is logged in to get an ID. If the user is not logged in, you get a '0' back.

server_name

Hostname of our server.

remote_host

Client IP address or hostname connecting to us.

user_agent

The browser identification string. (May be empty, forged, etc.)

referer

URL (string) where the user came from. (May be empty, forged, etc.)

Action Messages

Actions or other code can leave messages for other actions. These messages are typically tagged errors so the action and/or view knows how to sort through them, but it's not required. For instance, if a login fails we want to be able to indicate this so that the login box can display the right type of error message. Normally you'd set the messages directly in the action (via add_view_message()), but in the (fairly rare) case where the two are disconnected you can deposit error messages in the request and the relevant action will know where to pick them up when it's later instantiated.

action_messages( $action_name, [ \%messages ] )

Retrieve hashref of messages for action $action_name, case-insensitive. Overwrite all existing messages with \%messages if it's provided.

Returns: hashref of action messages for action $action_name; empty hashref if $action_name not provided.

add_action_message( $action_name, $msg_name, $msg )

Adds an individual message $msg_name with message $msg to $action_name. The $msg_name may be whatever you like, but frequently it's an object field name.

Returns: $msg set

SUBCLASSING

If you're extending OpenInteract to a new architecture and need to create a request adapter it's probably best to look at an existing one to see what it does. (Working code is always more up-to-date than documentation...) That said, here are a few tips:

  • If your architecture is deployed under a particular URL you should set this as soon as possible. Do so using the assign_deploy_url() method of the context. See OpenInteract2::Request::CGI for an example.

Other than that take a look at OpenInteract::Request::Standalone. It forces you to deal with parameters and file uploads yourself, but it may be the path of least resistance.

Methods

_set_upload( $name, $upload )

Associates the OpenInteract2::Request::Upload $upload object with $name.

Returns: the upload object

_parse_cookies( [ $cookie_header_string ] )

Pass in the value from the client for the HTTP 'Cookie' header and the string will be parsed and the name/value pairs assigned to the request object. If $cookie_header_string not passed in we look in the cookie_header property.

SEE ALSO

Class::Factory

OpenInteract2::Request::Apache

OpenInteract2::Request::CGI

OpenInteract2::Request::LWP

OpenInteract2::Request::Standalone

COPYRIGHT

Copyright (c) 2002-2003 Chris Winters. 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>