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
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:
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' );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' );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).
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.
server_name
remote_host
user_agent
referer
theme
theme_values
session
action_name
task_name
auth_user
auth_group
auth_is_admin
auth_is_logged_in
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.
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_url( $full_url )
This method is implemented in this class but is called by the implementing subclass. The subclass should pass the full, absolute URL in so the url_absolute and url_relative properties are properly set. This also sets the action name and task for use by the controller.
_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.
BUGS
None known.
TO DO
Nothing known.
SEE ALSO
OpenInteract2::Request::Apache
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>