NAME

App::ZofCMS::Plugin::StartPage - ZofCMS plugin that redirects the user to a page choosen by the user

SYNOPSIS

<tmpl_var name='plug_start_page_form'>

In ZofCMS Template:

plugins => [ qw/StartPage/ ],

plug_start_page => {
    pages => [
        'http://google.ca/'             => 'Google',
        'http://zoffix.com/'            => 'Zoffix Znet Portal',
        'http://mind-power-book.com/'   => 'Mind Power Book',
    ],

    # everthing below is optional; default values are shown
    dsn           => "DBI:mysql:database=test;host=localhost",
    user          => '',
    pass          => undef,
    opts          => { RaiseError => 1, AutoCommit => 1 },
    no_redirect   => undef,
    table         => 'users',
    login_col     => 'login',
    page_col      => 'start_page',
    login         => sub { $_[0]->{d}{user}{login} },
    label_text    => 'Start page:',
    default_page  => undef,
    submit_button => q|<input type="submit" class="input_submit"|
                        . q| value="Save">|,
},

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means to present a user a form where they can select one of several pages to which to redirect (selection is stored in a SQL database). The module was designed to provide means to let the users select their landing pages upon logon, which is how the name of the module originated.

This documeantation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template.

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

`plugins`

plugins => [ qw/StartPage/ ],

Mandatory. You need to include the plugin in the list of plugins to execute.

`plug_start_page`

plug_start_page => {
    pages => [
        'http://google.ca/'             => 'Google',
        'http://zoffix.com/'            => 'Zoffix Znet Portal',
        'http://mind-power-book.com/'   => 'Mind Power Book',
    ],

    # everthing below is optional; default values are shown
    dsn           => "DBI:mysql:database=test;host=localhost",
    user          => '',
    pass          => undef,
    opts          => { RaiseError => 1, AutoCommit => 1 },
    no_redirect   => undef,
    table         => 'users',
    login_col     => 'login',
    page_col      => 'start_page',
    login         => sub { $_[0]->{d}{user}{login} },
    label_text    => 'Start page:',
    default_page  => undef,
    submit_button => q|<input type="submit" class="input_submit"|
                        . q| value="Save">|,
},

Mandatory. Takes either a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_start_page key as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameters hashref, and $config is the App::ZofCMS::Config object. Possible keys/values for the hashref are as follows:

`pages`

plug_start_page => {
    pages => [
        'http://google.ca/'             => 'Google',
        'http://zoffix.com/'            => 'Zoffix Znet Portal',
        'http://mind-power-book.com/'   => 'Mind Power Book',
    ],
...

plug_start_page => {
    pages => sub {
        my ( $t, $q, $config ) = @_;
        return $t->{plug_start_page__pages_arrayref};
    }
...

Mandatory. Takes an arrayref or a subref as a value. If subref is specified, its return value must be either an arrayref or undef (or empty list). The return value will be assigned to pages as if it was already there. The @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameters hashref, and $config is the App::ZofCMS::Config object.

If pages is not specified, or its arrayref is empty, or if the subref returns undef, empty arrayref or empty list, plugin will stop further execution.

The arrayref must have an even number of elemeants that are to be thought of as keys and values (the arrayref is used to preserve order). The "keys" of the arrayref represent URIs to which to redirect the user and the "values" must be strings that represent the human readable description of their corresponding "keys". These will be shown as text in the <option>s in the start page selection form; the order being the same as what you specify here, in pages.

`dsn`

plug_start_page => {
    dsn => "DBI:mysql:database=test;host=localhost",
...

Optional, but with a useless default. The dsn key will be passed to DBI's connect_cached() method, see documeantation for DBI and DBD::your_database for the correct syntax for this one. The example above uses MySQL database called test which is located on localhost. Defaults to: DBI:mysql:database=test;host=localhost

`user`

plug_start_page => {
    user => '',
...

Optional. Specifies the user name (login) for the database. This can be an empty string if, for example, you are connecting using SQLite driver. Defaults to: '' (empty string)

`pass`

plug_start_page => {
    pass => undef,
...

Optional. Same as user except specifies the password for the database. Defaults to: undef (no password)

`opts`

plug_start_page => {
    opts => { RaiseError => 1, AutoCommit => 1 },
...

Optional. Will be passed directly to DBI's connect_cached() method as "options". Defaults to: { RaiseError => 1, AutoCommit => 1 }

`no_redirect`

plug_start_page => {
    no_redirect => undef,
...

Optional. Takes either true or false values. If set to a true value, plugin will not redirect the user and will present them with a start page selection form (see HTML::Template VARIABLES and GENERATED HTML CODE sections below). If set to a false value, plugin will look up which start page the user chose and redirect to it and will call exit() right after that. If user has not chosen any start pages, plugin will redirect the user to the URI specified by default_page (see below) and will also call exit(). If default_page is not specified, plugin will NOT redirect the user anywhere, and will simply stop processing (without calling exit()). Defaults to: undef (process redirections)

`table`

plug_start_page => {
    table => 'users',
...

# Minimal needed table:
CREATE TABLE `users` (
    `login`      TEXT,
    `start_page` TEXT
);

Optional. Specifies the name of the SQL table into which to store start page choices the user selects. Configuration of the table can be anything you like, but must at least contain two columns (as shown in the example above): the login_col (see below) that can be of any type; and page_col that needs to be of type suitable for storing the URIs of your start pages. NOTE: the table must already contain a row with the user's login, as plugin only calls SQL UPDATE, which won't save user's start page unless their row is already in the database. Defaults to: users

`login_col`

plug_start_page => {
    login_col => 'login',
...

Optional. Takes a string as value that specifies the name of a column in table table that contains usernames of users. The plugin will look for login (see below) value in this column in order to find saved start page. Defaults to: login

`page_col`

plug_start_page => {
    page_col => 'start_page',
...

Optional. Takes a string as value that specifies the name of a column in table table that contains users' start page settings. The plugin will read/write into this column, so make sure that data type is suitable for storing your start page URIs. Defaults to: start_page

`login`

plug_start_page => {
    login => sub { $_[0]->{d}{user}{login} }, # @_ = ( $t, $q, $config );
...

plug_start_page => {
    login => 'zoffix',
...

Optional. Takes a subref, undef, or a string as a value. Specifies the login of the current user that plugin will use to look up saved start page setting. If undef is specified or the subref returns an undef or an empty list, plugin will stop further processing. If subref is specified, its return value will be assigned to login as if it was already there. The @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameters hashref, and $config is the App::ZofCMS::Config object. Defaults to: sub { $_[0]->{d}{user}{login} }

`label_text`

plug_start_page => {
    label_text => 'Start page:',
...

Optional. Takes a string as a value. Specifies the text for the <label> elemeant in the start page selection form. Defaults to: Start page:

`default_page`

plug_start_page => {
    default_page => undef,
...

plug_start_page => {
    default_page => 'http://mind-power-book.com/',
...

Optional. Takes either undef or a string as a value. If set to a string and the user does not have saved start page setting, then the user will be redirected to default_page URI. If default_page is not specified (undef), then user will not be redirected anywhere (that is, when their start page was never chosen). Defaults to: undef

`submit_button`

plug_start_page => {
    submit_button => q|<input type="submit" class="input_submit"|
                        . q| value="Save">|,
...

Optional. Takes HTML code as a value. Specifies the HTML code for the submit button of the start page selecting form. Feel free to insert here any extra HTML code you might require. Defaults to: <input type="submit" class="input_submit" value="Save">

HTML::Template VARIABLES

If no_redirect argumeant (see above) is set to a true value, the plugin will stick plug_start_page_form variable into {t} ZofCMS Template special key. It will contain the start page selecting form in it.

<tmpl_var name='plug_start_page_form'>

GENERATED HTML CODE

Here's what plugin generated start page selecting form looks like:

<p class="success-message">Successfully saved</p>

<form action="" method="POST" id="plug_start_page_form">
<div>
    <input type="hidden" name="page" value="/index">
    <input type="hidden" name="plugsp_save_settings" value="1">

    <label for="plugsp_page">Start page:</label
    ><select id="plugsp_page" name="plugsp_page"
    >
        <option value="http://google.ca/">Google</option>
        <option value="http://zoffix.com/"
            selected
        >Zoffix Znet Portal</option>
        <option value="http://mind-power-book.com/">Mind Power Book</option>
    <input type="submit" class="input_submit" value="Save">
</div>
</form>

The value for page hidden <input> is derived by the plugin automagically. The <p class="success-message">Successfully saved</p> elemeant is shown only when the user saves their settings. The text for the <label> is controlled by the label_text argumeant, and the HTML code of the submit button is controlled by submit_button.

REQUIRED MODULES

Plugin likes to play with these modules:

App::ZofCMS::Plugin::Base => 0.0106,
HTML::Template            => 2.9,
DBI                       => 1.609,

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.

To install App::ZofCMS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::ZofCMS

CPAN shell

perl -MCPAN -e shell
install App::ZofCMS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

plug_start_page

pages

dsn

user

pass

opts

no_redirect

table

login_col

page_col

login

label_text

default_page

submit_button