NAME

IWL::Static - a Static file handler

INHERITANCE

IWL::Error -> IWL::RPC -> IWL::Static

DESCRIPTION

IWL::Static provides a simple method for serving static content to a server

SYNOPSIS

In order to serve static content through IWL::Static, a few steps must be taken.

To use IWL::Static static internally, either the STATIC_URI_SCRIPT, or STATIC_LABEL configuration options must be set in your iwl.conf file. The STATIC_URI_SCRIPT option points to the script, which will serve the static content. The DOCUMENT_ROOT option should also be set, unless the files to be served use relative URIs (the IWL static files use absolute URIs). If the user wants to include more URIs, along with the default IWL ones, the STATIC_URIS option must also be set.

The Perl script, which is referenced by STATIC_URI_SCRIPT, will have the following code in its most simplest form:

 #! /usr/bin/perl
 use IWL::Static;

 IWL::Static->new->handleRequest;

This simple script will fetch all required content, which is inside the STATIC_URIS, as well as the default IWL static content, and will send it to the server with the appropriate header.

If the STATIC_LABEL option is set to a true value, the static content files will be labeled with a unique GET parameter, and the web server will be responsible for serving them.

CONSTRUCTOR

IWL::Static->new ([%ARGS])

Where %ARGS is an optional hash parameter with with key-values. See IWL::RPC::new for supported parameters

METHODS

addURI (URI => RECURSIVE, ...)

Adds a URI for static content to the list of known URIs

Parameters: URI - a URI, can be either a URI to a directory, or a file, or a list of those, RECURSIVE - if the URI is a directory, whether to to add all of its children

Note: An initial list of known URIs is obtained from a colon (':') separated list of URIs in the STATIC_URIS config parameter of IWL::Config, as well as the installation URIs for IWL's own static content

handleRequest (%OPTIONS)

Handles static file requests by checking whether the user script is invoked with a request for certain file, and if the file exists in one of the predefined static URIs, its contents are sent back to the server

Parameters: %OPTIONS - a hash of options. The following key-pairs are recognised:

header

An optional header hashref, or coderef, which will overwrite the default header parameters. If the parameter is a coderef, it should return a hashref which will be used for overriding. It will receive the content URI and its estimated MIME Type as its two parameters.

mimeType

An optional string or coderef. If the value is a string, it will be used as the content's mime type. If the value is a coderef, it will be called with the URI as its parameter, and its return value will be used as a mime type for the content

addRequest (URI)

Changes the URI into a static request, if the STATIC_URI_SCRIPT option is set in the %IWLConfig. It does not change the URI otherwise. This method is used by IWL::Widgets, which use static content, such as an IWL::Image.

Parameters: URI - a URI, or a list of URIs, which will be handled by the static uri handler script

addMultipleRequest (URIS)

Changes the URIS into a static request, if the STATIC_URI_SCRIPT and STATIC_UNION options are set in the %IWLConfig. Otherwise, returns a false value. The request will later pull the content of these URIS using a single request.

Parameters: URI - an array reference of URIs, which will be handled by the static uri handler script

LICENCE AND COPYRIGHT

Copyright (c) 2006-2008 Viktor Kojouharov. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perldoc perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.