/ 
CatalystX-Usul-0.16.1
/ CatalystX::Usul::Controller

Name

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

Version

This document describes CatalystX::Usul::Controller version v0.16.$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

action_source

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

config_class

String which defaults to Config

fs_class

String which defaults to FileSystem

global_class

String which defaults to Config::Globals

help_class

String which defaults to Help

model_base_class

String which defaults to Base

String which defaults to Navigation

realm_class

String which defaults to UsersSimple

usul

A Class::Usul object

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

CatalystX::Usul::TraitFor::BuildingUsul
CatalystX::Usul::TraitFor::Controller::Cookies
CatalystX::Usul::TraitFor::Controller::ModelHelper
CatalystX::Usul::TraitFor::Controller::PersistentState
CatalystX::Usul::TraitFor::Controller::TokenValidation

Subroutines/Methods

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

auto

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

begin

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"

deny_access

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

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

end

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

error_page

$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

get_browser_state

$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

loc

$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

redirect_to_path

$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

_get_user_object

$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

_is_user_agent_ok

$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

_parse_HasActions_attr

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

_redirect_to_page

$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

__accepted_content_types

$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.

__get_language

$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)

__is_language

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

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

__preferred_content_type

$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

None

Dependencies

Catalyst::Controller
Class::Usul
CatalystX::Usul::Moose
HTTP::Headers::Util
Parse::HTTP::UserAgent
TryCatch

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 RoxSoft.co.uk>

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