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 GET and POST 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.
To install the module project local, copy it into the uHTML
subdirectory of the
script-directory of the website. To install it globally, copy it into the uHTML
subdirectory of a perl-library directory.
It is allowed to use this library under the actual GNU General Public License. The name of this library and it's author is to be named in all derivations.
This uHTML::request library requires besides of the uHTML library the libraries: LWP::MediaTypes, URI::Escape, IO::Handle, Time::Local and POSIX.
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.
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 uHTML::request; # $uHTML::FileName = '' ; # uncomment for production code uHTML::request->process() ;
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
uHTML::request data structure is intended to be manipulated only by uHTML::request methods, but may be helpful for read only access. Directly accessed values aren't necessary set or valid. The data structure may change any time and should be accessed for debug purposes only.
ENV
: - current environmentRoot
: - effective document rootPath
: - path as array reference, Path[0] contains the server namepath
: - path as stringfile
: - current file with pathFile
: - name of current fileBaseName
: - name of current file with no extensionsRequest
: - current HTTP request URI as array reference, Request[0] contains the server nameRequestFile
: - current HTTP request fileRequestName
: - current HTTP request file with no extensionsrequest
: - current HTTP request as stringhome
: - server directory containing the site's datalength
: - length of the HTTP responseHTML
: - the HTTP responseQuery
: - HTTP Query data (GET)Post
: - HTTP Post data (POST)Data
: - combined HTTP Query and Post dataRecvCookie
: - received cookieSendCookie
: - cookie to be sentHead
: - HTTP head dataPostString
: - HTTP Post data (POST) as stringInitRequest
: - functions called on $request->Init()
FinishRequest
: - functions called on $request->Finish()
new, Init, Finish, QueryData, PostData, Data, Cookie, ContentType, Headers, setHeader, putHeader, FileData, codeFile, putFile, process, HTML, file, File, BaseName, Path, RequestPath, RequestName, Root, home, ServerPath
The method new creates a new uHTML::request object.
$env
$env
must refer to the environment
hash associated with the actuall HTTP request. If missing, the current
environment is used instead.
uHTML::request->new
( $env );
The method Init initialises the HTTP request processing and calls all module specific init functions.
&initFunc($request)
&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.
$request->Init
(\&initFunc);
The method Finish ends the HTTP request processing and calls all module specific finish functions.
&finishFunc($request)
&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.
$request->Finish
(\&finishFunc);
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.
$Name
$request->QueryData
($DataName);
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:
multipart/form-data
$Name
$request->PostData
($PicName);
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:
multipart/form-data
$Name
$request->Data
($PicName);
The method Cookie reads and sets cookies. To set (or delete) a cookie $Value must be defined.
$Name
$Value
""
do not removes the cookie.
$expire
0
deletes the cookie.
$path
/
” is used.
$host
$ENV{'SERVER_NAME'}
” is used.
$JS
$request->Cookie
($Name);
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.
$Type
$Type
sets the content type
used in the HTTP headers.
$request->ContentType
();
The method Headers returns 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.
$length
$request->Headers
();
The method putHeader sends the HTTP headers to the STDOUT
.
$length
$request->putHeader
();
The method setHeader ads a HTTP header.
$name
$value
' '
if missing.
$request->setHeader
( 'x-PITarget',$request->Data
('PITarget') );
The method FileData gives access to the content of the uHTML file.
$request->FileData
();
The method codeFile translates internally uHTML into HTML.
$request->codeFile
();
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 .
$env
$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.
$request->process
();uHTML::request->process
( $env );
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
.
$request->putFile
();
The method file returns the complete name including the path of the current request file.
$request->file
();
The method File returns the name of the current request file without the path .
$name
$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.
$request->File
('/index.uhtml');
The method BaseName returns the name of the current file without the path and without extension.
$request->BaseName
();
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.
$idx
$idx
indicates the desired part of the Path.
It can contain a range. The value 0
returns the name of the host.
$request->Path
();
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.
$idx
$idx
indicates the desired part of the Request Path.
It can contain a range. The value 0
returns the name of the website.
$request->RequestPath
();
The method RequestName returns the name of the current request file without the path and without extension.
$request->RequestName
();
The method Root returns the current document directory.
$request->Root
();
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 '#'
.
$Path
$request->ServerPath
('/index.uhtml');