NAME

WWW::Slides - serve presentations on the Web

VERSION

This document describes WWW::Slides version 0.0.4

SYNOPSIS

   # It can be as simple as this:
   use WWW::Slides qw( spawn_server );
   my $pid = spawn_server(
      {
         slides          => \@slide_filenames, 
         http_port       => 50505,
         controller_port => 50506,
      }
   );

    
  
  

DESCRIPTION

This module contains facade functions to easily use the various modules available in this library. For this reason, this module is function-oriented.

Spawning Servers

The spawn_server() sub will spawn a talk for you, providing sensible defaults. You can override each of them, of course. The spawned server is a daemon, with root directory set to /, closed filehandles, etc.

You can provide your fully built WWW::Slides::Talk object (or equivalent) to the function; in this case, you're only actually using the daemonising property of the function itself.

It's much easier to use the function with a minimum of required parameters and let the code do its work, though. At the very basic level, you should provide at least the following parameters:

slides

the slides to serve. The easier approach here is pass a reference to an array of filenames of HTML files, and let the code load them and figure out how to put them into separated slides.

http_port

where the server should listen for incoming connections from browsers.

controller_port

where the server should listen for incoming TCP connections from speakers.

So, the basic invocation is as simple as this:

   use WWW::Slides qw( spawn_server );
   my $pid = spawn_server(
      {
         slides          => \@slide_filenames, 
         http_port       => 50505,
         controller_port => 50506,
      }
   );

In this case, browsers should point to http://server.address:50505/ and speakers should connect to port 50506. That's it.

The WWW::Slides system has a minimum integration with a logging system. It should work seamlessly with Log::Log4perl, but you're not obliged to use it; if you don't have it, it's ok even if you want to actually log something, because there is a minimal implementation of the relevant part of Log::Log4perl. If you have a $logger object that conforms to Log::Log4perl (and it's easy to conform to it), you can pass it and have logs sent to it:

   use WWW::Slides qw( spawn_server );
   use Log::Log4perl qw( get_logger );
   # ... initialise Log::Log4perl...

   my $logger = get_logger();
   my $pid = spawn_server(
      {
         slides          => \@slide_filenames, 
         http_port       => 50505,
         controller_port => 50506,
         logger          => $logger,
      }
   );

In case all you want is to send log messages on standard error, just say that you want to debug and the code will happily build up a logger for you behind the scenes:

   use WWW::Slides qw( spawn_server );
   my $pid = spawn_server(
      {
         slides          => \@slide_filenames, 
         http_port       => 50505,
         controller_port => 50506,
         debug           => 1,
      }
   );

See all the options for spawn_server in the INTERFACE section.

INTERFACE

my $pid = spawn_server($config_hash_ref);

This function lets you spawn a Talk server with a minimum of energy. The server 'daemonizes' itself, avoiding the double-fork but making all the other steps (changing the current directory, calling setsid(), closing handles, etc.).

It gets its parameters through an hash reference containing them. The parameters are listed in the following list, note that those indicated as 'mandatory' are not actually mandatory, because they will be ignored if the talk parameter is provided.

accepts_detaches

When unset, the talk server will not accept detaches, i.e. all attendees will stick to the main slide served by the talk.

On the other hand, when users can detach and actually detach themselves, they do not follow the "mainstream" presentation, but can wander on their own.

This parameter is optional, defaults to true.

controller

If you provide a controller, this controller should adhere to the controller interface in WWW::Slides::Controller::Single. If you just need to have a TCP controller, skip this parameter and let the sub do its work, setting the TCP port with the controller_port parameter. On the other hand, if you have your smart controller go ahead.

Either this or controller_port are mandatory.

controller_port

If all you need is just a basic TCP-based controller, fill in this parameter with the port the controller should bind to, it's all that you need. WWW::Slides::Controller::TCP will be invoked for you behind the scenes.

Either this or controller are mandatory.

debug

When set, STDERR will not be closed and a suitable logger will be built for you if you don't provide one.

http_port

This parameter sets the port to which the spawned server will listen for incoming connections from browsers.

It is mandatory.

logger

You can pass a reference to a logger object, e.g. a Log::Log4perl object.

This parameter is optional. Defaults to 'no logger' unless debug is set, in which case a logger is built up for you to log on STDERR.

must_book

When set, the spawned server will accept only client connections for booked attendees. See WWW::Slides::Talk for details.

This parameter is optional and defaults to false.

ping_interval

At least every ping_interval some data are sent to the client browser, in order to keep the TCP connection up.

This parameter is optional, default is 10 seconds.

slides

You can pass variuos things through this parameter:

• an object conforming to the WWW::Slides::SlideShow interface;

• a filehandle;

• a filename;

• a reference to an array of filenames.

In the last three cases, a WWW::Slides::SlideShow object will be built up behind the scenes, and the parameter will be passed to the read() method. Refer to WWW::Slides::SlideShow for details about it.

This parameter is mandatory.

talk

if you provide this parameter, you don't have to provide anything else (except debug, if you want). This is the object that will be used as talk, most probably a WWW::Slides::Talk or something with a run() method. In this case, you take all the burden of building up a suitable talk.

DIAGNOSTICS

The functions will balk (ehr, croak) at you if you don't provide enough parameters or something wrong happens. The given error should be meaningful by itself.

CONFIGURATION AND ENVIRONMENT

WWW::Slides requires no configuration files or environment variables.

DEPENDENCIES

WWW::Slides has virtually no dependency by itself, apart the non-core semi-standard module version. If you let the functions do their work automatically, you will probably bump into the dependencies of the various modules in the WWW::Slides distribution.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through http://rt.cpan.org/

AUTHOR

Flavio Poletti <flavio [at] polettix [dot] it>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Flavio Poletti <flavio [at] polettix [dot] it>. All rights reserved.

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

Questo modulo è software libero: potete ridistribuirlo e/o modificarlo negli stessi termini di Perl stesso. Vedete anche perlartistic e perlgpl.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

NEGAZIONE DELLA GARANZIA

Poiché questo software viene dato con una licenza gratuita, non c'è alcuna garanzia associata ad esso, ai fini e per quanto permesso dalle leggi applicabili. A meno di quanto possa essere specificato altrove, il proprietario e detentore del copyright fornisce questo software "così com'è" senza garanzia di alcun tipo, sia essa espressa o implicita, includendo fra l'altro (senza però limitarsi a questo) eventuali garanzie implicite di commerciabilità e adeguatezza per uno scopo particolare. L'intero rischio riguardo alla qualità ed alle prestazioni di questo software rimane a voi. Se il software dovesse dimostrarsi difettoso, vi assumete tutte le responsabilità ed i costi per tutti i necessari servizi, riparazioni o correzioni.

In nessun caso, a meno che ciò non sia richiesto dalle leggi vigenti o sia regolato da un accordo scritto, alcuno dei detentori del diritto di copyright, o qualunque altra parte che possa modificare, o redistribuire questo software così come consentito dalla licenza di cui sopra, potrà essere considerato responsabile nei vostri confronti per danni, ivi inclusi danni generali, speciali, incidentali o conseguenziali, derivanti dall'utilizzo o dall'incapacità di utilizzo di questo software. Ciò include, a puro titolo di esempio e senza limitarsi ad essi, la perdita di dati, l'alterazione involontaria o indesiderata di dati, le perdite sostenute da voi o da terze parti o un fallimento del software ad operare con un qualsivoglia altro software. Tale negazione di garanzia rimane in essere anche se i dententori del copyright, o qualsiasi altra parte, è stata avvisata della possibilità di tali danneggiamenti.

Se decidete di utilizzare questo software, lo fate a vostro rischio e pericolo. Se pensate che i termini di questa negazione di garanzia non si confacciano alle vostre esigenze, o al vostro modo di considerare un software, o ancora al modo in cui avete sempre trattato software di terze parti, non usatelo. Se lo usate, accettate espressamente questa negazione di garanzia e la piena responsabilità per qualsiasi tipo di danno, di qualsiasi natura, possa derivarne.

cpanm WWW::Slides

perl -MCPAN -e shell
install WWW::Slides