The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
OpenInteract-1.99_00
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;
 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 'server_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:

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

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

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

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>