/ 
POE-XUL-0.0601
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::XUL

NAME

POE::Component::XUL - POE::XUL server

SYNOPSIS

use POE;
use POE::Component::XUL;

POE::Component::XUL->spawn( { 
                                port => 8001,
                                root => '/var/poe-xul/',
                                alias => 'POE-XUL',
                                opts  => {},
                                timeout => 30 * 60,
                                logging => {},
                                apps => {   
                                    MyApp => 'My::App',
                                    # ....
                                } 
                          } );
$poe_kernel->run();

DESCRIPTION

POE::Component::XUL handles all POE and HTTP events for a POE::XUL server.

POE::Component::XUL creates an HTTP server with POE::Component::Server::HTTP.

POE::Component::XUL can server up static files, and a limited form of server-side includes "BUILD FILES". XUL events (under the /xul URI) are passed to POE::XUL::Controler to be handled.

STATIC FILES

Any request not under /xul is handled as a static file. For directories, you must provide an index.html; no autoindexing is provided.

The response's content type is guessed at with MIME::Types.

BUILD FILES

A sub-set of static files are the build files. They allow you to create a response by including multiple files into one response. This cuts down on HTTP trafic while still allowing you to maintain various parts in individual files and not creating complex Makefiles. Of course, all the sub-files must share a same mime-type.

Given a request for a /path/file.ext, if the build file /path/file.ext.build exists, it is used to build the response. The response is saved in the cache file /path/file.ext.cache and which is sent for subsequent requests for /path/file.ext, unless /path/file.ext.build is updated.

A build file is expected to be a text file. It may contain the following command:

@include

@include "other-file.ext"

The file <other-file.ext> is included at that point in the file. The sub-files are themselves parse like build files; they may include further files.

Example

my-xbl.xml.build:

<?xml version="1.0"?>
<bindings
    xmlns="http://www.mozilla.org/xbl"
    xmlns:xbl="http://www.mozilla.org/xbl"
    xmlns:html="http://www.w3.org/1999/xhtml"
    xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
@include "tag1.xml"
@include "tag2.xml"
@include "tag3.xml"
</bindings>

tag1.xml:

<binding id="tag1">
    <content><children /></content>
    <implementation> ... </implementation>
</binding>

and similarly for tag2.xml and tag3.xml.

METHODS

spawn

Spawns the component. Arguments are:

apps

A hash ref that defines the applications this server handles. Hash keys are the names of the application, as used in the initial URL /start.xul?AppName. The values may be either package names or coderefs. In the former case, the object method spawn is called when a new application instance is needed. In the latter case, the coderef is called.

port

The TCP port the server should listen too. Defaults to what you specified to Makefile.PL (8077).

root

Path of the static files handled by the server. Must include start.xul and the javascript client library. Defaults to what you specified to Makefile.PL (/usr/local/poe-xul).

timeout

The number of seconds of inactivity before an application instance is shutdown. Activity is currently defined as events sent from the javascript client library.

alias

The session alias for this component. Defaults to component-poe-xul.

opts

Hashref of options passed to POE::Session/create.

logging

Parameters passed to POE::XUL::Logging.

EVENTS

shutdown

As all good components should, POE::Component::XUL has a shutdown event, which also tells the POE::Component::Server::HTTP to 'shutdown'.

AUTHOR

Philip Gwyn <gwyn-at-cpan.org>

CREDITS

Based on XUL::Node by Ran Eilam, POE::Component::XUL by David Davis, and of course, POE, by the illustrious Rocco Caputo.

SEE ALSO

perl(1), POE::XUL, POE::Component::Server::HTTP.