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 is 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 is 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:
a single field, in which case you must specify a strptime format in
$formatmultiple fields where
$nameis 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:
a single field, in which case you must specify a strptime format in
$formatmultiple fields where
$nameis 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 is not logged in they will always get your login page. This is done in the OpenInteract2::Auth class -- if the user is not 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 value associated with the name, not a CGI::Cookie object.
If you pass in a $value along with $name then it is 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.
Language/Localization
language() (read-only)
Returns the language(s) chosen for this particular request. This is one of the few context-sensitive properties. If called in list context it will return a list of all languages supported in this request, even if only one is available. If called in scalar context it will return the first (and presumably most important) language.
See OpenInteract2::Manual::I18N for how we find the language(s) desired for this request.
language_handle() (read-only)
A Locale::Maketext object from which you can get localized messages.
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 stateful session for the current user.
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 is 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 is 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.
auth_clear
Clears out all the 'auth_*' properties to undef -- generally only used when you want to log a user out for the current request.
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 is 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 would 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 is 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 is 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 is 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 is 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
Parent initialization
_parse_cookies()
Reads the cookie_header property and parses it into the name/value pairs returned from the cookie() method. So your adapter must set this header to have the cookies created and/or create the cookies yourself using cookie(). (OpenInteract2::Request::Standalone is an example of doing both)
_create_session()
Reads in the cookie with the name defined in the constant SESSION_COOKIE from OpenInteract2::Constants and uses its value as the session ID passed to OpenInteract2::SessionManager to create the session, which is stored in the session property.
_find_language()
...
SEE ALSO
OpenInteract2::Request::Apache
OpenInteract2::Request::Standalone
COPYRIGHT
Copyright (c) 2002-2004 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>