Peter Flanigan > CatalystX-Usul-0.17.1 > CatalystX::Usul::Controller



Annotate this POD



Open  0
View/Report Bugs
Module Version: v0.17.1   Source  

Name ^

CatalystX::Usul::Controller - Application independent common controller methods

Version ^

This document describes CatalystX::Usul::Controller version v0.17.$Rev: 1 $

Synopsis ^

   package YourApp::Controller::YourController;

   BEGIN { extents qw(CatalystX::Usul::Controller) }

Description ^

Provides methods common to all controllers. Implements the "big three" Catalyst API methods; begin, auto and end

Configuration and Environment ^

Defines the following attributes


String which defaults to action. A key in the stash where meta information about actions is stored


String which defaults to Config


String which defaults to FileSystem


String which defaults to Config::Globals


String which defaults to Help


String which defaults to Base


String which defaults to Navigation


String which defaults to UsersSimple


A Class::Usul object

Extends Catalyst::Controller. Applies the controller roles including;


Subroutines/Methods ^

Private methods begin with an _ (underscore). Private subroutines begin with __ (two underscores)


Control access to actions based on user roles and ACLs

This method will return true to allow the dispatcher to forward to the requested action, or this method will redirect to either the profile defined authentication action or one of the predefined default actions

These actions are permanently on public access; about, access_denied, captcha, action_closed, help, and view_source. Anonymous access is granted to actions that have the Public attribute set

Each action has a state attribute which is stored in the action's configuration file. Setting the actions state attribute to a value greater than 1 has the effect of closing the action to access. Instead the request is redirected to the action_closed action which is implemented by the root controller. The state attribute is set/unset by the access_control action in the Admin controller

The list of users/groups permitted to access an action (ACL) is stored in the configuration file. If an ACL has not been created only members of the support group will be allowed to access the action. ACLs can contain both user ids and group names. Group names are prefixed with an '@' character to distinguish them from user ids

The special ACL 'any' will allow any request to access the action. If the action does not permit public access requests from unknown users will be redirected to the authentication action which is defined in the package configuration

Requests for access to an action for which there is no authorisation will be redirected to the access_denied action which is implemented in the root controller

If no ACL for an action can be determined the the request is redirected to the error_page action


This method stuffs the stash with most of data needed by Template::Toolkit to generate a 'blank' page. Begin methods in controllers forward to here. They can alter the stash contents before and after the call to this method

The file default.json contains the meta data for each controller. Each controller has two configuration files which contain the controller specific data. One of the files is language independent and contains elements that define form fields and form keys. The language dependent file contains all the literal text strings used by that controller

The content type is either set from the configuration or if negotiate_content_type is true it is set to the first element of the array returned by "__accepted_content_types". The content type is used to lookup the current view in the content_map

Once the view has been selected it's deserialization method is called as required

The requested language is obtained by calling "__get_language"

Once the language is known the stash is further populated by calling "_stash_per_request_config"


   $bool = $self->deny_access( $c );

Returns true if the user is denied access to the requested action


Calls add_token if the current page should contain a token and the plugin has been loaded. Traps and processes any errors. Forwards to the render method which has the action class attribute set to RenderView


   $self->error_page( $c, $error_message_key, @args );

Generic error page which displays the specified message. The error message is localized by calling the localize method in the base class


   $self->get_browser_state( $c, $c->config );

Recover information stored in the browser state cookie. Uses the CatalystX::Usul::TraitFor::Controller::Cookies module if it's loaded


   $local_text = $self->loc( $c->stash, $key, @options );

Localizes the message. Calls "localize" in Class::Usul::L10N. Adds the constant DEFAULT_L10N_DOMAINS to the list of domain files that are searched. Adds $c->stash->{language} and $c->stash->{namespace} (search domain) to the arguments passed to localize


   $self->redirect_to_path( $c, $action_path, @args );

Sets redirect on the response object and then detaches. Defaults to the default_action config attribute if the action path is null

Private Methods ^


   $c->stash->{user} = $self->_get_user_object( $c, $c->stash, $c->config );

Using this system, sessions do not expire for three months. Instead the user key is expired after a period of inactivity. This method recovers information about the user and stores it on the stash. Everywhere else the stashed information is used as required


   $bool = $self->_is_user_agent_ok( $c );

Detects use of the misery browser. Sets the skin to $c->config->{misery_skin} if its defined. Otherwise redirects to $c->config->{misery_page} if that is defined. Otherwise serves up a W3C validated page for Exploiter to render as garbage


Associates the HasActions method attribute with the action class defined in the action_class configuration attribute


   $self->_redirect_to_page( $c, $page_name );

Takes a simple page name works out it's private path and then calls "redirect_to_path"

Private Subroutines ^


   $types = __accepted_content_types( $c->req );

Taken from jshirley's Catalyst::Action::REST

Returns an array reference of content types accepted by the client

The list of types is created by looking at the following sources:

Content-type header

If this exists and the request is a GET request, this will always be the first type in the list

Content-type parameter

If the request is a GET request and there is a "content-type" parameter in the query string, this will come before any types in the Accept header

Accept header

This will be parsed and the types found will be ordered by the relative quality specified for each type

If a type appears in more than one of these places, it is ordered based on where it is first found.


   $language = __get_language( $c->stash, $c->req, $c->config );

In order of precedence uses; the first capture argument, the accept-language headers from the request, the configuration default and finally the hard coded default which is en (English)


   $bool = __is_language( $candidate, \@languages );

Tests to see if the given language is supported by the current configuration


   $content_type = __preferred_content_type( $c->req, $c->config );

Returns the first accepted content type if the negotiate_content_type config attribute is true. Defaults to the config attribute content_type

Diagnostics ^


Dependencies ^


Incompatibilities ^

There are no known incompatibilities in this module

Bugs and Limitations ^

There are no known bugs in this module. Please report problems to the address below. Patches are welcome

Author ^

Peter Flanigan, <Support at>

License and Copyright ^

Copyright (c) 2014 Pete Flanigan. All rights reserved

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

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE

syntax highlighting: