NAME

Gadgets - Go Go Gadgets!

DESCRIPTION

Gadgets is a framework built out of a suite of Perl modules that makes
gluing HTML::Mason code and XML::Comma easy and fun.

Gadgets.pm is the entry point for Gadgets, providing the global $g
object. Contained in $g are objects of several flavors, including an
Authentication class, a Configuration class, and a Resolver class. See
the SEE ALSO section below for links to those modules.

METHODS

simple_handle_request

Basic (and usually adequate) method to call from handler.pl to handle
each Apache request. See APAHCE CONFIGURATION, below.

implements ( api => , [ path => ] )

Look up which installed Gadget or Gadgets "implement" a particular API.
This method is used by the resolver to find components using the special
Gadget ampersand call syntax:

  $m->comp ( '/&Test/foo' );
  <& '/&Test/foo' &>

When passed a path argument, this method returns a single par_file name
(or undef, if no installed Gadget has declared that it implements the
requested API). If multiple Gadgets are installed, the conf system is
checked for an indication of which Gadget is preferred for the supplied
path. If no relevant conf value is found, the Gadget with the oldest
install_time value is returned.

When not passed a path argument, this method returns a list of installed
Gadgets that implement the API.

By convention, interface names are in CamelCase, so that Mason calls to
interface-defined components are easier to read.

Example conf keys:

  PATH           KEY                 VALUE             GADGET
  /              'FourColorSkin'  'Sunset Skin'      core_impl
  /foo_blog      'FourColorSkin'  'Dark Sky Skin'    core_impl

auth

returns the underlying Gadgets::AuthManager object. See
Gadgets::AuthManager for the "auth" methods.

conf

returns the underlying Gadgets::Configuration object. See
Gadgets::Configuration for the "conf" methods.

APACHE CONFIGURATION

Two levels of configuration are required: a few lines in Apache's
httpd.conf file (or equivalent), and a Mason handler.pl file.

In httpd.conf:

  PerlModule       Gadgets::ParResolver;
  PerlTransHandler Gadgets::ParResolver::trans_handler

and something like the following, to have Mason handle part (or all) of
Apache's location space:

<Location /> SetHandler perl-script PerlHandler HTML::Mason </Location>
PerlRequire /web-working/handler.pl

Here is a complete handler.pl example:

  package HTML::Mason;

  use HTML::Mason;
  use Apache::Constants qw(:common);
  use Apache::Request;

  use strict;

  {
    package HTML::Mason::Commands;
    use vars qw( $g );

    use XML::Comma;
    use Gadgets;

    $g = Gadgets->new
      ( verbose        => 0,
        comp_root      => '/web-working',
        resolver_class => 'Gadgets::Resolver',
        data_dir       => '/usr/local/apache/mason_data',
        error_mode     => 'output', );
  }

  sub handler {
    my ($r) = @_;

    return -1  if  $r->uri() =~ m|^/static/|;
    my $status;

    $status = $HTML::Mason::Commands::g->simple_handle_request ( $r );
    return $status;
  }

  1;

You may have noticed the "simple_handle_request" method, used in our
handler sub above. Here is the code for that method, in its entirety:

  sub simple_handle_request {
    my ( $self, $r ) = @_;

    return DECLINED  if  $r->content_type  and
                         $r->content_type =~ m|^httpd|;

    if ( $r->content_type                 and
         $r->content_type  !~  m|^text| ) {
      if ( $r->pnotes('PAR') ) {
        return $self->{resolver}->send_raw_file ( $r );
      } else {
        return DECLINED;
      }
    }

    return $self->{apache_handler}->handle_request ( $r );
  }

Many handler.pl setups have complex setups to determine whether (and
how) Mason should serve top-level requests. If you need to integrate the
Gadgets resolver into such a setup, you'll need to code your own version
of the logic above.

It's important to avoid asking the Gadgets resolver to handle "httpd/*"
content types. Apache uses some heavy wizardry under the covers to make
requests for directories to eventually turn into requests for index.html
files. (And along the way pick up missing trailing slashes.) We're not
going to be able to do this as well as Apache, so we needs to get out of
its way as much as possible.

It's also worth noting that Gadgets will often include binary files that
need to be served without the benefit of Mason componentization. The
"simple_handle_request" routine assumes that all "text/*" content types
are fair game for Mason, but that all other content types will be sent
byte-for-byte to the client. Your rules for this may differ.

DEMO

There is a misc/demo directory in the distribution, with a demo Gadget
par file and gadget spec.