NAME
VERSION
Version 1.81
DESCRIPTION
This library provides handling of HTTP requests for uHTML. It pre-processes and normalizes HTTP-Request variables like e.g. path and directory names, handles bGE/b and bPOS/b data, handles cookies, generates HTTP headers and translates uHTML in HTML.
The probably most useful function of uHTML::request is the invocation of module specific functions before and after each request processing. This allows other modules to process data provided with a HTTP-Request before and after the generation of HTML code, allowing to alter the content of the HTML content and the HTTP headers according to the data provided with the request.
REQUIREMENTS
This uHTML::request library requires besides of the uHTML library the libraries: LWP::MediaTypes, URI::Escape, IO::Handle, Time::Local and POSIX.
EXAMPLE
The following full working examples show the basic invocation of uHTML::request. For matching configurations, more file examples, uHTML deployment details and additional explanations see the uHTML description.
uHTML::request with CGI
The first example addresses CGI servers. The hook.pl program must be called by the webserver via a appropriate server request analogous to the basic uHTML invocation, e.g. by redirecting the requests in a .htaccess file.
hook.pl
#!/usr/bin/perl
use strict;
use uHTML::request;
# $uHTML::FileName = '' ; # uncomment for production code
uHTML::request->process() ;uHTML::request with FCGI
The second example addresses FCGI servers. To simplify the server deployment PSGI with Plack is used. Plack expects a perl executable psgi which follows the PSGI specifications. This executable takes the place of the hook.pl in the first example.
psgi
use strict;
use uHTML::request;
sub
{
my $env = shift ;
$env->{'PATH_INFO'} = $env->{'URI'} ; # nginx+PLACK needs it for the compability with Apache CGI
# $uHTML::FileName = '' ; # uncomment for production code
my $request = uHTML::request->new( $env ) ;
return [ 200,$request->Headers(),$request->HTML() ] if $request ;
return [ 404,[ 'Content-Type' => 'text/plain' ],[ 'Not Found' ] ] ;
}The Plack PSGI server is started with plackup -s FCGI -S /tmp/uHTML -a /usr/lib/perl/*/uHTML/psgi. For the matching configuration of the nginx server see the uHTML description
Description of uHTML::request methods
new($env)
Overview
The method new creates a new uHTML::request object.
Parameters
$env
The optional parameter $env must refer to the environment hash associated with the actuall HTTP request. If missing, the current environment is used instead.
Example
my $request = uHTML::request->new( $env );Init(\&initFunc)
Overview
The method Init initialises the HTTP request processing and calls all module specific init functions.
Parameters
&initFunc($request)
The parameter &initFunc must refer to a function which will be called before the uHTML file gets processed. The function is called with the reference to the current uHTML::request ($request). Typically this function will process data sent to the website.
Example
$request->Init(\&initFunc);Finish(\&finishFunc)
Overview
The method Finish ends the HTTP request processing and calls all module specific finish functions.
Parameters
&finishFunc($request)
The parameter &finishFunc must refer to a function which will be called after the uHTML file gets processed and before the HTTP headers get generated. The function is called with the reference to the current uHTML::request ($request). Typically this function will finish processing of data sent to the website, update server files and databases and set cookies and data which will be sent to the browser.
Example
$request->Finish(\&finishFunc);ENV()
Overview
The method ENV returns the current environment. By passing an argument the environment can be set as well, this shouldn't be done except one knows very well what one does.
Example
$env = $request->ENV();QueryData($Name)
Overview
The method QueryData returns the query data associated with $Name, speak data that was transmitted in the URI with the GET method. It returns context depending either an array containing all values associated with $Name in list context or the “first” value in scalar context.
Parameters
$Name
Name of the data.
Example
$Data = $request->QueryData($DataName);PostData($Name)
Overview
The method PostData returns the post data associated with $Name, speak data that was transmitted with the POST method via STDIN. It returns context depending either an array containing all values associated with $Name in list context or the "first" value in scalar context.
When the data was transmitted as multipart/form-data the returned value is a reference to a HASH (or and array of HASH references in list context) containing the data. The HASH has the following values:
- name - name of the data
- label - label provided with the data
- length - data length
- data - the data itself
- boundary - boundary used in multipart/form-data
Parameters
$Name
Name of the data.
Example
$Picture = $request->PostData($PicName);Data($Name)
Overview
The method Data returns a combination of post and query data associated with $Name, speak data that was transmitted either with the GET or the POST method. It practically lifts the difference between GET and POST data. It returns context depending either an array containing all values associated with $Name in list context or the "first" value in scalar context.
When the data was transmitted as multipart/form-data the returned value is a reference to a HASH (or and array of HASH references in list context) containing the data. The HASH has the following values:
- name - name of the data
- label - label provided with the data
- length - data length
- data - the data itself
- boundary - boundary used in multipart/form-data
Parameters
$Name
Name of the data.
Example
$Picture = $request->Data($PicName);Cookie($Name,$Value,$expire,$path,$host,$JS)
Overview
The method Cookie reads and sets cookies. To set (or delete) a cookie $Value must be defined.
Parameters
$Name
Cookie name.
$Value
Cookie value. A value of "" do not removes the cookie.
$expire
Cookie expiration time in seconds (suffix none or s), hours (suffix h), days (suffix d), months (suffix m), or years (suffix y). The value 0 deletes the cookie.
$path
Cookie path. If not defined the path "/" is used.
$host
The host associated with the cookie. If not defined, "$ENV{'SERVER_NAME'}" is used.
$JS
If true, then the cookie is available via JavaScript.
Example
$Cookie = $request->Cookie($Name);ContentType($Type)
Overview
The method ContentType returns the data type of the request file. It relays rather on the name of the file than on the content. Optionally the content type can be enforced by passing a parameter.
Parameters
$Type
The optional parameter $Type sets the content type used in the HTTP headers.
Example
$ContentType = $request->ContentType();Headers($length)
Overview
The method Headers returns a reference to the HTTP headers in PSGI format, a simple array, where the name and the value of each header entry follow each other and the array consists of value pairs.
Parameters
$length
If given it overrides the internally calculated length of the HTML output.
Example
$headers = $request->Headers();putHeader($length)
Overview
The method putHeader sends the HTTP headers to the STDOUT.
Parameters
$length
If given it overrides the internally calculated length of the HTML output.
Example
$request->putHeader();setHeader($name,$value)
Overview
The method setHeader ads a HTTP header.
Parameters
$name
Header name. Must be given.
$value
Header value. Is set to ' ' if missing.
Example
$request->setHeader( 'x-PITarget',$request->Data('PITarget') );FileData()
Overview
The method FileData gives access to the content of the uHTML file.
Example
$FData = $request->FileData();codeFile()
Overview
The method codeFile translates internally uHTML into HTML.
Example
$request->codeFile();process($env)
Overview
The method process processes a CGI HTTP request and sends the result to STDOUT. It can be either invoked as a method of an existing request or as package function. In the latter case process creates an own new uHTML::request and uses it to process the (CGI) HTTP request .
Parameters
$env
The optional parameter $env is only used if a new uHTML::request is created. It must refer to the environment hash associated with the actuall HTTP request. If missing, the current environment is used instead.
Example
$request->process();
uHTML::request->process( $env );putFile()
Overview
The method putFile sends if existent the processed file content to STDOUT. If the processed content is missing, it sends the original file to STDOUT.
Example
$request->putFile();file()
Overview
The method file returns the complete name including the path of the current request file.
Example
$FName = $request->file();File()
Overview
The method File returns the name of the current request file without the path .
Parameters
$name
Name of the new input file. If the $name starts with '/' the name is interpreted as relative to the effective document directory $request->{'Root'}. Otherwise it is interpreted as relative to the current directory. If the file is not found, the parameter is ignored.
Example
$FName = $request->File(/index.uhtml');BaseName()
Overview
The method BaseName returns the name of the current file without the path and without extension.
Example
$Name = $request->BaseName();Path($idx)
Overview
The method Path returns the path of the current request. It returns context depending either an array containing the all path elements in list context or a string in scalar context.
Parameters
$idx
The optional parameter $idx indicates the desired part of the Path. It can contain a range. The value 0 returns the name of the host.
Example
$Path = $request->Path();RequestPath($idx)
Overview
The method RequestPath returns the path used in the current HTTP request. It returns context depending either an array containing the all path elements in list context or a string in scalar context.
Parameters
$idx
The optional parameter $idx indicates the desired part of the Path. It can contain a range. The value 0 returns the name of the website.
Example
$Site = $request->RequestPath(0);RequestName()
Overview
The method RequestName returns the name of the file used in the current request without the path and without extension.
Example
$Name = $request->RequestName();Root()
Overview
The method Root returns the current document directory.
Example
$Docs = $request->Root();ServerPath($Path)
Overview
The method ServerPath calculates the actual path on the server from a given $Path according to the uHTML path name conventions. Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.
Parameters
$Path
Path to convert.
Example
$File = $request->ServerPath('/index.uhtml');
SEE ALSO
perl(1), http://www.uhtml.de/en/doc/request.uhtml, uHTML
AUTHOR
Roland Mosler (Roland.Mosler@Place.Ug)
COPYRIGHT
Copyright 2009 Roland Mosler. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 620:
Deleting unknown formatting code T<>
Deleting unknown formatting code T<>