NAME

Controller - Root application controller/dispatcher

SYNOPSIS

    my ($cgi, $request, $headers, $content);

    BEGIN {
        Pinwheel::Controller::connect(':controller/:action/:id');
    }

    $cgi = new CGI();
    $request = {
        host => $ENV{'HTTP_HOST'},
        path => $ENV{'PATH_INFO'},
        base => '/'
    };
    ($headers, $content) = Controller::dispatch($request);
    print $cgi->header(%$headers);
    print $content;

DESCRIPTION

Dispatch an HTTP request to the appropriate controller package and return the generated headers and content.

ROUTINES

connect(...)

Add a route to the list recognised by the application. See "connect" in Pinwheel::Mapper.

dispatch(REQUEST, ARGS)

TODO, document me.

url_for([NAME], PARAMS)

Generate a URL from a route (added with "connect"). See "generate" in Pinwheel::Mapper.

As well as the params allowed by $mapper->generate, the following additional params are supported:

only_path

Boolean; defaults to true.

Normally, URLs for this site will be partial, e.g. "/some/path". Setting only_path = 0> causes such URLs to become absolute, e.g. "http://host.example.com/some/path".

redirect_to(URL) or redirect_to([NAME], PARAMS)

Render a 302 redirect. The target URL (i.e. the "Location" header of the response) is found as follows:

The form redirect_to($url) is recognised by the fact that $url contains at least one "/". The url is prefixed by "http://" plus this request's "Host" header, unless $url matches m[^\w+://].

Otherwise, the URL is found by calling url_for([NAME], PARAMS, only_path => 0).

render(OPTIONS)

TODO, document me.

render_to_string(OPTIONS)

TODO, document me.

render_error(STATUS, MESSAGE)

TODO, document me.

Note: not exportable.

Before doing whatever it is that render_error does, it calls the sub given by $Controller::error_logger in void context with three arguments: STATUS, MESSAGE, and the error depth. (TODO: define the error depth).

$Controller::error_logger defaults to \&Controller::default_error_logger, which shows the error via Carp::cluck if the STATUS is 500.

render_404(MSG)

Calls render_error(404, MSG)

render_500(MSG)

Calls render_error(500, MSG)

set_header(KEY, VALUE)

TODO, document me.

$time = request_time()

Returns the start time of the request, as specified by the 'time' argument to dispatch. (Hence, expressed as seconds since the epoch).

$time = request_time_model()

Like request_time, but returns the answer as a Pinwheel::Model::Time object. (Always returns a new model object, so it's safe to modify the returned object if you wish).

expires_in($seconds)

Adds headers via set_header such that the response expires $seconds seconds after the request time.

expires_at($time)

Adds headers via set_header such that the response expires at the time specified by $time (which should be a Pinwheel::Model::Time object).

expires_now()

Adds headers via set_header such that the response expires now.

accepts(...)

TODO, document me.

respond_to("$format"[, $handler_sub], ...)

respond_to is called with an alternating list of (format-name, handler-coderef) pairs, except that each handler-coderef is optional. For example:

  respond_to('html', 'txt', 'xml' => \&xml_handler, 'json');

Once a format is selected (TODO, document this) the handler is then invoked; if no handler was specified, the following is used:

            render(format => $format);

TODO, also document 404 "Format not supported" errors and the format stack.

params(KEY, [KEY, ...])

TODO, document me.

query_params(...)

TODO, document me.

format(...)

TODO, document me.

set_base_format(...)

TODO, document me.

set_format_param($name)

Sets $format_param. This specifies the name of the route parameter used to select among multiple formats, as used by accepts and respond_to.

The default format_param is "format".

expand_static_path(...)

TODO, document me.

set_static_root(ROOT)

TODO, document me.

set_templates_root(ROOT)

TODO, document me.

preload_templates()

Preloads all templates found under the templates_root.

EXPORTS

Exported by default: url_for redirect_to render render_to_string render_404 render_500 set_header expires_in expires_at expires_now accepts respond_to params query_params

May be exported: connect dispatch format set_base_format set_format_param expand_static_path set_static_root set_templates_root request_time request_time_model

AUTHOR

A&M Network Publishing <DLAMNetPub@bbc.co.uk>