NAME

POE::XUL::POE - A POE::XUL application that doesn't use POE::XUL::Application

SYNOPSIS

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

POE::Component::XUL->spawn( { apps => {   
                                    Test => 'My::App',
                                    # ....
                            } } );
$poe_kernel->run();

##########
package My::App;
use POE::XUL::Node;

sub spawn
{
    my( $package, $event ) = @_;
    my $self = bless { SID=>$event->SID }, $package;
    POE::Session->create(
        object_states => [ $self => 
            [ qw( _start boot Click shutdown other_state ) ] ],
    );
}

#####
sub _start {
    my( $self, $kernel ) = @_[ OBJECT, KERNEL ];
    $kernel->alias_set( $self->{SID} );
}


#####
sub boot {
    my( $self, $kernel, $event, $app ) = @_[ OBJECT, KERNEL, ARG0, ARG1 ];
    $self->{D} = Description( "do the following" );
    $self->{W} = Window( HBox( $self->{D}, 
                               Button( label => "click me", 
                                       Click => 'Click' ) ) );
    $event->finish;
}

#####
sub Click {
    my( $self, $kernel, $event ) = @_[ OBJECT, KERNEL, ARG0 ];
    $event->done( 0 );
    $kernel->yield( 'other_state', $event );
}

sub other_state {
    my( $self, $kernel, $event ) = @_[ OBJECT, KERNEL, ARG0 ];
    $event->wrap( sub {
            $self->{D}->textNode( 'You did it!' );
            $self->{W}->firstChild->appendChild( $self->{B2} );
        } );
    $event->finished;
}

DESCRIPTION

The application

POE::XUL applications generaly have one POE::session per application instance. This POE session is spawned when a boot request is recieved from the client. The session then must handle a 'boot' event, where-in it creates a Window element and its children. The application session is kept active, handling the user events it has defined, until the users stops using it, that is a period of inactivity. The session is then sent a 'timeout' event followed by a 'shutdown' event.

spawn

sub spawn {
    my ( $package, $event ) = @_;
    # must create a session
    POE::Session->create( 
            inline_states => { _start => \&_start }
            args => [ $event->SID ]
        );
}

# That session must have the SID as an alias
sub _start {
    my( $kernel, $SID ) = @_;
}

It must set the session's alias to the application's SID, available via $event->SID. All furthur communication with the application instance happens by posting POE events to the SID.

POE::XUL::Event and POE::XUL::ChangeManager

Only changes that are wrapped in an Event will be seen by the ChangeManager and be mirrored in the client. POE::XUL::Event will wrap the initial event and call it with "call" in POE::Kernel. If you wish to post further POE events, you must set the Event's done to 0, and wrap any node changes with "wrap" in POE::XUL::Event. You must call "finished" in POE::XUL::Event to complete the request.

"wrap" in POE::XUL::Event also provides error handling; if your code dies, the error message will be displayed in the browser.

AUTHOR

Philip Gwyn <gwyn-at-cpan.org>

COPYRIGHT AND LICENSE

Copyright 2007-2008 by Philip Gwyn. All rights reserved;

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

SEE ALSO

perl(1), POE::XUL::Node, POE::XUL::Event, POE::XUL::Controler, POE::XUL::Application, http://www.prototypejs.org/.