NAME

CGI::Application::URIMapping - A dispatcher and permalink builder

SYNOPSIS

  # your.cgi
  use MyApp::URIMapping;
  
  MyApp::URIMapping->dispatch();
  
  
  package MyApp::URIMapping;
  
  use base qw/CGI::Application::URIMapping/;
  use MyApp::Page1;
  use MyApp::Page2;
  
  
  package MyApp::Page1;
  
  use base qw/CGI::Application/;
  
  # registers subroutine ``page1'' for given path
  MyApp::URIMapping->register({
    path  => 'page1/:p1/:p2?',
    query => [ qw/q1 q2 q3/ ]
  });
  
  sub page1 {
    my $self = shift;
    
    # if URI is not in permalink style, redirect
    return if $self->normalize_uri;
    
    ...
  }
  
  # build_uri, generates: http://host/page1/p-one?q1=q-one&q3=q-three
  my $permalink = MyApp::Page1->build_uri([{
    p1 => 'p-one',
    q1 => 'q-one',
    q3 => 'q-three',
  }]);

DESCRIPTION

CGI::Application::URIMapping is a dispatcher / permalink builder for CGI::Application. It is implemented as a wrapper of CGI::Application::Dispatch.

As can be seen in the synopsis, CGI::Application::URIMapping is designed to be used as a base class for defining a mapping for each CGI::Application-based web application.

METHODS

register

The class method assigns a runmode to more than one paths. There are various ways of calling the function. Runmodes of the registered packages are automatically setup, and Build_uri method will be added to the packages.

  MyApp::URIMapping->register('path');
  MyApp::URIMapping->register('path/:required_param/:optional1?/:optional2?');
  
  MyApp::URIMapping->register({
    path  => 'path',
    query => [ qw/n1 n2/ ],
  });
  
  MyApp::URIMapping->register({
    rm       => 'run_mode',
    path     => 'path',
    protocol => 'https',
    host     => 'myapp.example.com',
  });
  
  MyApp::URIMapping->register({
    app  => 'MyApp::Page2',
    rm   => 'run_mode',
    path => [
      'path1/:p1/:p2?/:p3?' => {
        query => [ qw/n1 n2/ ],
      },
      'path2' => {
        query => [ qw/p1 p2 p3 n1 n2/ ],
      },
    ],
  });

The attributes recognized by the function is as follows.

app

Name of the package in which the run mode is defined. If ommited, name of the current package is being used.

rm

Name of the runmode. If omitted, basename of the first path attribute is being used.

path

A path (or an array of paths) to be registered for the runmode. The syntax of the paths are equivalent to that of CGI::Application::Dispatch with the following exceptions. The attributes app and rm need not be defined for each path, since they are already specified. Procotol, host, query attributes are accepted.

protocol

Specifies protocol to be used for given runmode when building a permalink.

host

Limits the registration to given host if specified.

query

List of parameters to be marshallised when building a premalink. The parameters will be marshallized in the order of the array.

all_param

The function is an accessor / mutator for uniformly handling path parameters and query parameters.

  my $value = $cgi_app->all_param($name);   # read paramater
  
  $cgi_app->all_param($name, $value);       # set parameter

The setter first tries to read from $cgi_app->param($name), and then $cgi_app->query->param($name). The getter sets the value to $cgi_app->param($name, $value).

build_uri

The function is automatically setup for the registered CGI::Application packages.

  MyApp::Page1->build_uri();      # builds default URI for page1
  
  MyApp::Page1->build_uri({       # explicitly set runmode
    rm  => 'page1',
  });
  
  MyApp::Page1->build_uri({       # specify parameters and protocol
    params   => [{
      p1 => 'p-one',
      n1 => 'n-one',
    }],
    procotol => 'https',
  });
  
  MyApp::Page1->build_uri({       # just override 'p1'
    params => [
      {
        p1 => 'p-one',
      },
      $cgi_app,
      $cgi_app->query,
    ],
  });

If called with a hash as the only argument, the function recognizes the following attributes. If called with an array as the only argument, the array is considered as the params attribute.

rm

Name of the runmode. If omitted, the last portion of the package name will be used uncamelized.

protocol

Protocol.

params

An array of hashes or object containing values to be filled in when building the URI. The parameters are searched from the begging of the array to the end, and the first-found value is used. If the array element is an object, its param method is called in order to obtain the variable.

validate_uri

The function, which is automaticaly setup as a instance method of CGI::Application, checks whether the current URI is conforms to the registered format.

  $cgi_app->validate_uri();
  
  $cgi_app->validate_uri({        # explicitly specify runmode
     rm => 'page1',
  };
  
  $cgi_app->validate_uri({        # set extra query parameters to be allowed
     extra => [ qw/__extra1 __extra2/ ],
  });

The function accepts following attributes.

rm

Runmode. If omitted, uncamelized basename of the package is used.

extra

Array of query args to be ignored while validating the parameters received.

The return value of the function is one of the following constants.

URI_IS_PERMALINK

Current URI conforms the registered format.

URI_UNKNOWN_PARAM

Current URI contains an unknown query parameter.

URI_PATH_PARAM_IN_QUERY

A parameter expected in path_info is being received as a query parameter.

URI_OMITTABLE_PARAM

A parameter that should be omitted (since it contains the default value) exists.

The constants are importable by specifying :constants attribute.

  use CGI::Application::URIMapping qw/:constants/;

AUTHOR

Copyright (c) 2007 Cybozu Labs, Inc. All rights reserved.

written by Kazuho Oku <kazuhooku@gmail.com>

LICENSE

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

See http://www.perl.com/perl/misc/Artistic.html

cpanm CGI::Application::URIMapping

perl -MCPAN -e shell
install CGI::Application::URIMapping