The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Maplat-0.995
River stage zero No dependents
++
/ Maplat::Web::BaseModule

NAME

Maplat::Web::BaseModule - base module for web modules

SYNOPSIS

This module is the base module any web module should use.

DESCRIPTION

When writing a new web module, use this module as a base:

  use Maplat::Web::BaseModule;
  @ISA = ('Maplat::Web::BaseModule');

new

This creates a new instance of this module. Do not call this function directly, use the "configure" call in Maplat::Web.

register

This function needs to be overloaded in every web module. This function is run during startup once some time after new(). Within this function (and ONLY within this function) you can call register_*() functions to register your callbacks/hooks.

reload

This function is called some time after register() and may be called again while the webgui is running. Everytime reload() is called, you should empty all cached data in this application and reload it from the sources (if applicable).

endconfig

This is a callback, called when all modules are configured. During this callback, you should close all open filehandles, network ports and database connections. The cause of this requirement is, that the user may configure a forking webserver and filehandles/network connections should not be forked. In the case of network connections and database handles, this might confuse the protocol (and certainly will screw with database transactions). In the case of filehandles you will run into similar problems.

register_webpath

This function registers a function of its own module as a webpage. It takes two arguments, the webpath and the function name.

  ...
  sub register {
    $self->register_webpath("/foo/bar", "getFooBar");
  }
  ...
  sub getFooBar {
    my %webdata = (
        $self->{server}->get_defaultwebdata(),
        PageTitle   =>  $self->{pagetitle},
        webpath     =>  $self->{admin}->{webpath},
        subject     =>  $subject,
        mailtext   =>  $mailtext,
    );
    ...
    my $template = $self->{server}->{modules}->{templates}->get("sendmail", 1, %webdata);
    return (status  =>  404) unless $template;
    return (status  =>  200,
            type    => "text/html",
            data    => $template);
  }

It is possible to register multiple webpaths within the same web module.

The function should return a fully rendered page in the above shown data structure.

register_prefilter

This function registers a function of its own module as a prefilter (called before the actual rendering module is called to render the page). It takes one argument, the function name.

The function itself gets called with the $cgi object in question. The module may either modify the CGI object, or rather more common, return a rendered web page on its own (for example to redirect the browser).

If it returns undef, the page handling continues as usual, if it returns a webpage, this is taken as the actual rendered page and the "real" rendering module is not called at all.

  ...
  sub register {
    $self->register_prefilter("filterFooBar");
  }
  ...
  sub filterFooBar {
    my ($self, $cgi) = @_;

    my $webpath = $cgi->path_info();

    # if there is a redirect for the current path, just return the
    # pre-parsed response
    if(defined($self->{paths}->{$webpath})) {
        return %{$self->{paths}->{$webpath}};
    }

    return; # No redirection
  }

register_postfilter

This function registers a function of its own module as a postfilter (called after the actual rendering module is called to render the page). It takes one argument, the function name.

The function itself gets called with the $cgi object in question plus the $header and the $result references of the rendered page. The module can change $header and $result as it sees fit. It should return undef in any case.

  ...
  sub register {
    $self->register_postfilter("filterFooBar");
  }
  ...
  sub filterFooBar {
      my ($self, $cgi, $header, $result) = @_;
  
      # Just add the cookie to the header
      if($self->{cookie}) {
          $header->{cookie} = $self->{cookie};
      }

      return;
  }

register_defaultwebdata

This function registers a function of its own module to add to the %defaultwebdata hash usually used by every module to start its own webpage hash. It takes one argument, the function name to call

The function itself gets called with the a reference to a %webdata hash. The module can change it as it sees fit, but generally should not delete any keys.

  ...
  sub register {
    $self->register_defaultwebdata("get_defaultwebdata");
  }
  ...
  sub get_defaultwebdata {
      my ($self, $webdata) = @_;
  
      if($self->{currentData}) {
          $webdata->{userData} = $self->{currentData};
      }
  }

register_task

This function registers a function of its own module as a cyclic worker function. It takes one argument, the name of the cyclic function, for example:

  ...
  sub register {
    $self->register_worker("doWork");
  }
  ...
  sub doWork {
    # update $bar with @foo
    ...
  }

It is possible to register multiple cyclic functions within the same web module.

register_loginitem

This function registers a function of its own module as a hook for whenever a user logs in. It takes one argument, the function to call.

The function itself gets called with the username and sessionid.

  ...
  sub register {
    $self->register_loginitem("on_login");
  }
  ...
  sub on_login {
    my ($self, $username, $sessionid) = @_;
    # do something
  }

register_logoutitem

This function registers a function of its own module as a hook for whenever a user logs out. It takes one argument, the function to call.

The function itself gets called with the sessionid.

  ...
  sub register {
    $self->register_logoutitem("on_logout");
  }
  ...
  sub on_logout {
    my ($self, $sessionid) = @_;
    # do something
  }

register_sessionrefresh

This function registers a function of its own module as a hook for whenever a logged in user loads a page. It takes one argument, the function to call.

The function itself gets called with the sessionid.

This is usefull to detect stale sessions.

  ...
  sub register {
    $self->register_sessionrefresh("on_refresh");
  }
  ...
  sub on_refresh {
    my ($self, $sessionid) = @_;
    # do something
  }

register_prerender

This function registers a function of its own module as a hook for everytime a page is ready to be rendered by the template engine (it gets triggered by the TemplateCache module).

The function itself gets called with a reference to %webdata.

This is usefull to when you need to modify %webdata, but need all the data from the userpage available. This is for example used in generating the dynamic menus and views in module Login.

  ...
  sub register {
    $self->register_prerender("on_prerender");
  }
  ...
  sub on_prerender {
    my ($self, $webdata) = @_;
    if($webdata->{foo} eq $bar) {
       $webdata->{baz} = 1;
    }
  }

register_cleanup

Register a callback for "cleanup" operations after a page has been rendered. This might for example be a function in a database module that makes sure there are no open transactions.

get_defaultwebdata

See register_defaultwebdata()

Configuration

This module is not used directly and doesn't need configuration.

Dependencies

This module does not depend on other worker modules (but modules using it will, depending on which register_* callbacks they use)

SEE ALSO

Maplat::Worker

AUTHOR

Rene Schickbauer, <rene.schickbauer@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008-2011 by Rene Schickbauer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.