The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Egg-Release-1.16
River stage two • 17 direct dependents • 17 total dependents
++
/ Egg::Dispatch::Runmode

NAME

Egg::Dispatch::Runmode - Standard subdispatch class for Egg.

SYNOPSIS

Dispatch file example.

  package MYPROJECT::D;
  use strict;
  use MYPROJECT::D::Help;
  use MYPROJECT::D::Root;
  
  __PACKAGE__->run_modes(
    _begin  => \&_begin,
    _default=> \&_default,
    _end    => \&_end,
    help    => {
      _begin => sub {},  # The operation of '_begin' of top-level is stopped.
      _end   => sub {},  # The operation of '_end' of top-level is stopped.
      faq    => \&MYPROJECT::D::Help::faq,
      },
    members => {
      _begin  => \&MYPROJECT::D::Root::_begin,
      _default=> \&MYPROJECT::D::Root::_default,
      _end    => \&MYPROJECT::D::Root::_end,
      profile => sub {
        my($self, $e)= @_;
        $e->template('profile.tt');
        },
      },
    );
  
  __PACKAGE__->default_mode('default');
  
  # Only when operating by CGI.
  __PACKAGE__->mod_param('mode');
  
  sub _default {
    ....
  }
  
  ... Additionally, necessary code.

DESCRIPTION

This dispatch distributes processing based on HASH set to run_modes.

* HASH of a multiple structure is supported.

* The final attainment point must become CODE reference.

* Dispatch is concretely defined by the following styles.

  package MYPROJECT::D;
  use strict;
  
  __PACKAGE__->run_modes(
    front_page => sub { ... },
    second_page=> {
      _default => sub { ... },
      sub_page => sub { ... },
      },
    ...
    );

This operates as follows.

  http://domain/front_page/
      =>  run_modes->{front_page} is called.
  
  http://domain/second_page/
      =>  run_modes->{second_page}{_default} is called.
  
  http://domain/second_page/sub_page/
      =>  run_modes->{second_page}{sub_page} is called.

If '_default' is put when the key done to agree to the hierarchy under the scanning is not found, it matches it to it.

* Please make the value of '_default' CODE reference.

  __PACKAGE__->run_modes(
    _default=> sub { ... default code },
    ...
    );

* The name of '_default' is revokable in the method of 'default_mode' beforehand.

  __PACKAGE__->default_mode('_index');

The processing after a prior thing like Catalyst is reproduced with '_begin' and '_end' key.

* Please make the value of '_begin' and '_end' CODE reference.

  __PACKAGE__->run_modes(
    _begin=> sub { ... begin code },
    _end  => sub { ... end code   },
    ...
    );

* Please put '_begin' and '_end' that doesn't do anything when you want to stop this on the way.

HASH and the regular expression can be used for the key by using Tie::RefHash as follows. Because Tie::RefHash is conveniently used, the 'refhash' function is available.

  __PACKAGE__->run_modes( refhash(
      qr/member_([a-z0-9]{8})/=> refhash(
        qr/([A-Z])([0-9]{7})/ => \&MYPROJECT::D::Member::id,
        _default=> \&MYPROJECT::D::Member::default,
        ),
      login=> refhash(
        { POST=> 'check' }=> sub { check code ... },
        ),
      { GET=> 'help' }=> sub { help code ... },
      ),
    ),

* It is sure to match it before and behind the regular expression. '^' and '$' need not be put. The thing that should be assumed to be '.+abc.+' to make it match on the way is noted.

This operates as follows.

 http://domain/member_hoge/
     => &MYPROJECT::D::Member::default($dispath, $e, ['hoge']);
  
  http://domain/member_hoge/A1234567/
     => &MYPROJECT::D::Member::id($dispath, $e, ['A', '1234567']);

* As for a rear reference for the regular expression, only the thing matched at the end can be acquired.

* A rear reference is passed to the third argument by the ARRAY reference. This value can be acquired from $e->stash->{_action_match}.

When HASH is used for the key, REQUEST_METHOD is definable POST and GET

* Even if REQUEST_METHOD is specified over two or more hierarchies, it is not significant because it scans from a top hierarchy.

This is NG.

  { GET=> 'foo' }=> {
    { POST=> 'boo'  }=> sub { ... },
    { GET => 'hoge' }=> sub { ... },
    },

This doesn't match to all POST requests by a hierarchical scanning of foo. Therefore, there is no thing that matches to foo->boo. Moreover, it is not necessary to specify GET with hoge. This only becomes only inefficient.

When you want to make the POST request matched to boo.

  foo=> {
    { POST=> 'boo'  }=> sub { ... },
    { GET => 'hoge' }=> sub { ... },
    },

It is the above-mentioned and the mistake is not found in the syntax. However, this doesn't operate normally. I think that being passed to Tie::RefHash after the key to the second hierarchy progresses the character string is a problem. Therefore, the key is not recognized as HASH.

Please use 'refhash' though it is troublesome for a moment.

  __PACKAGE__->run_modes=> (
    foo=> refhash(
      { POST=> 'boo' }=> sub { ... },
      { GET => 'hoge'  }=> sub { ... },
      hoge=> refhash(
        qr/regixp(...)/ => sub { ... },
        qr/id(...)/ => sub { ... },
        ),
      ),
    );

$e->snip can be usually used in mod_perl. Please define the parameter name to reproduce snip beforehand by the use of 'mode_param' method in usual CGI.

  __PACKAGE__->mode_param('m');
  __PACKAGE__->run_modes(
    hoge=> {
      foo=> {
        baa=> sub { ... },
        },
      },
    );

This operates as follows.

  http://domain/cgi-bin/trigger.cgi?m=hoge-foo-baa
      => run_modes->{hoge}{foo}{baa} is called.

METHODS

run_modes ( HASH )

It is a method for the prior definition of the operation mode.

The reference can be used for the key by using Tie::RefHash.

  package MYPROJECT::D;
  use strict;
  
  __PACKAGE__->run_modes(
    .... HASH
    );

default_mode ([DEFAULT_NAME]) or start_mode ([DEFAULT_NAME])

The name of the default key can be set.

  __PACKAGE__->default_mode('_index');

param_name ([REQUEST_NAME]);

The parameter name to acquire the mode when moving it with usual CGI is set.

  __PACKAGE__->param_name('mode');

mode_now ([NUMBER])

The character that converts an action now at the time of matched it when executing it for the modal parameter is returned.

* This is a method of utility for usual CGI.

When [NUMBER] is specified, the action to the upstairs layer of one is targeted.

  action value : [qw{ foo hoge now }]
  
  dispath->mode_now()  =>  foo-hoge-now
  
  dispath->mode_now(1) =>  foo-hoge
  
  dispath->mode_now(2) =>  foo
  
  dispath->mode_now(3) =>  '' # Dead letter character.

label ([NUMBER])

The label of each action hierarchy is returned by the ARRAY reference.

If the label is defined in run_modes, the label is preserved.

  run_modes( refhash(
    { ANY=> 'members',  label=> 'For member' }=> refhash(
      { ANY=> 'edit',   label=> 'Member information edit' }=> sub { ... },
      { ANY=> 'service' label=> 'Service' }=> sub { ... },
      ),
  ) );

* Please set the action key by using 'ANY' to make it match POST and GET any.

This is useful for making Topic PATH.

  my $topic= qq{ <a href="/">HOME</a> };
  for (0..$#{$e->action}) {
        my $path = join('/', @{$e->action}[0..$_]) || "";
        my $label= $e->dispatch->label($_) || next;
        $topic.= qq{ &gt; <a href="/$path">$label</a> };
  }

* When label is not defined, URI parts under the scanning are put as they are. The $e->escape_html passing might be safe.

page_title

Matched label or action key is returned.

Using it with the template is convenient.

  <title><% $e->escape_html($e->dispatch->page_title) %></title>

SEE ALSO

Egg::Release,

AUTHOR

Masatoshi Mizuno <lushe@cpan.org>

COPYRIGHT

Copyright (C) 2007 by Bee Flag, Corp. <http://egg.bomcity.com/>, All Rights Reserved.

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