NAME
App::ZofCMS::Plugin::AccessDenied - ZofCMS plugin to restrict pages based on user access roles
SYNOPSIS
plugins => [
{ AccessDenied => 2000 },
],
# this key and all of its individual arguments are optional
# ... default values are shown here
plug_access_denied => {
role => sub { $_[0]->{d}{user}{role} },
separator => qr/\s*,\s*/,
key => 'access_roles',
redirect_page => '/access-denied',
master_roles => 'admin',
no_exit => 0,
},
# this user has three roles; but this page requires a different one
d => { user => { role => 'foo, bar,baz', }, },
access_roles => 'bez',DESCRIPTION
The module is a plugin for App::ZofCMS that provides means to restrict access to various pages. It's designed to work in conjunction with App::ZofCMS::Plugin::UserLogin plugin; however, the use of that plugin is not required.
This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template
FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS
plugins
plugins => [
{ AccessDenied => 2000 },
],Mandatory. You need to include the plugin in the list of plugins to execute.
plug_access_denied
# default values shown
plug_access_denied => {
role => sub { $_[0]->{d}{user}{role} },
separator => qr/\s*,\s*/,
key => 'access_roles',
redirect_page => '/access-denied',
master_roles => 'admin',
no_exit => 0,
},
# or
plug_access_denied => sub {
my ( $t, $q, $config ) = @_;
return $hashref_to_assign_to_plug_access_denied_key;
},Optional. Takes either a hashref or a subref as a value. If not specified, plugin will still run, and all the defaults will be assumed. If subref is specified, its return value will be assigned to plug_access_denied as if it was already there. The @_ of the subref will contain $t, $q, and $config (in that order): where $t is ZofCMS Tempalate hashref, $q is query parameters hashref, and $config is App::ZofCMS::Config object. Possible keys/values for the hashref are as follows:
role
plug_access_denied => {
role => sub { $_[0]->{d}{user}{role} },
...Optional. Takes a subref as a value. This argument tells the plugin the access roles the current user (visitor) possesses and based on these, the access to the page will be either granted or denied. The @_ will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameter hashref, and $config is the App::ZofCMS::Config object. Defaults to: sub { $_[0]->{d}{user}{role} } (i.e. attain the value from the $t->{d}{user}{role}). The subref must return one of the following:
a string
plug_access_denied => {
role => sub { return 'foo, bar, baz' },
...If the sub returns a string, the plugin will take it as containing one or more roles that the user (visitor of the page) has. Multiple roles must be separated using separator (see below).
an arrayref
plug_access_denied => {
role => sub { return [ qw/foo bar baz/ ] },
...If sub returns an arrayref, each element of that arrayref will be assumed to be one role.
a hashref
plug_access_denied => {
role => sub { return { foo => 1, bar => 1 } },
...If hashref is returned, plugin will assume that the keys of that hashref are the roles; plugin doesn't care about the values.
separator
plug_access_denied => {
separator => qr/\s*,\s*/,
...Optional. Takes a regex (qr//) as a value. The value will be regarded as a separator for page's access roles (listed in key key, see below), the value in role (see above) if that argument is set to a string, as well as the value of master_roles argument (see below). Defaults to: qr/\s*,\s*/
key
plug_access_denied => {
key => 'access_roles',
...Optional. Takes a string as a value. Specifies the key, inside {t} ZofCMS Template hashref's special key, under which a string with page's roles is located. Multiple roles must be separated with separator (see above). User must possess at least one of these roles in order to be allowed to view the current page. Defaults to: access_roles (i.e. $t->{t}{access_roles})
redirect_page
plug_access_denied => {
redirect_page => '/access-denied',
...Optional. Takes a URI as a value. If access is denied to the visitor, they will be redirected to URI specified by redirect_page. Defaults to: /access-denied
master_roles
plug_access_denied => {
master_roles => 'admin',
...Optional. Takes the string a value that contains "master" roles. If the user has any of the roles specified in master_roles, access to the page will be granted regardless of what the page's required roles (specified via key argument) are. To disable master_roles, use empty string. To specify several roles, separate them with your separator (see above). Defaults to: admin
no_exit
plug_access_denied => {
no_exit => 0,
...Optional. Takes either true or false values as a value. If set to a false value, the plugin will call exit() after it tells the browser to redirect unauthorized user to redirect_page (see above); otherwise, the script will continue to run, however, note that you will no longer be able to "interface" with the user (i.e. if some later plugin dies, user will be already at the redirect_page). Defaults to: 0 (false)
REPOSITORY
Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS
BUGS
To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues
If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org
AUTHOR
Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)
LICENSE
You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.