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.

cpanm App::ZofCMS

perl -MCPAN -e shell
install App::ZofCMS