NAME

App::ZofCMS::Plugin::CurrentPageURI - ZofCMS plugin to automatically add current page URI into templates

SYNOPSIS

In your HTML::Template template:

    <tmpl_var escape='html' name='page'>
    <tmpl_var escape='html' name='page_q'>
    <tmpl_var escape='html' name='page_full'>

In your ZofCMS Template:

    plugins => [ qw/CurrentPageURI/ ],

If current page's URI is http://zcms/?text=lalala, the results are:

    /
    /?text=lalala
    http://zcms/?text=lalala

Optional configuration (defaults are shown):

    plug_current_page_uri => {
        prefix          => '',
        protocol        => 'http://',
        is_mod_rewrite  => 1,
        quiet_index     => 1,
    },

DESCRIPTION

The module is a ZofCMS plugin that provides means to stuff your HTML::Template template (or more accurately your {t} special key) with three variables that are representations of the current page's webroot-relative URI, webroot-relative URI with query parameters attached, and finally the full URI (with the protocol, domain name, and query parameters).

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

FIRST-LEVEL ZofCMS TEMPLATE KEYS

plugins

    plugins => [ qw/CurrentPageURI/ ],

First and obvious, you need to stick CurrentPageURI in the list of your plugins. NOTE: plugin will STILL run even if plug_current_page_uri is not specified (in that case, all default values will be assumed).

plug_current_page_uri

    # default values are shown
    plug_current_page_uri => {
        prefix          => '',
        protocol        => 'http://',
        is_mod_rewrite  => 1,
        quiet_index     => 1,
    },

Optional. Takes a hashref as a value that specifies plugin's configuration. Can be specified either in Main Config file, ZofCMS Template, or both, in which case all values will be congregated into one hashref with values in ZofCMS Template taking precedence. If not specified, all the defaults will be assumed. Possible keys/values are as follows:

prefix

    plug_current_page_uri => {
        prefix => '',
    ...

    plug_current_page_uri => {
        prefix => 'la_page_',
    ...

Optional. Takes a string as a value that specifies the prefix to use for the <tmpl_var> variables (see HTML::Template VARIABLES section below). For example, by default page_q variable is set to the current page plus query. If we set prefix to value la_page_, then la_page_page_q will be set to original page_q's value. Defaults to: '' (empty string)

protocol

    plug_current_page_uri => {
        protocol => 'http://',
    ...

    plug_current_page_uri => {
        protocol => sub {
            my ( $t, $q, $config ) = @_;
            return 'http://';
        },
    ...

Optional. Takes a string that contains the protocol to prepend to page_full variable (see below) or a subref that returns such a string. If subref is specified, its @_ array will contain: $t, $q, $config (in that order) where $t is ZofCMS Template hashref, $q is the query parameter hashref and $config is the App::ZofCMS::Config object. Defaults to: http://

is_mod_rewrite

    plug_current_page_uri => {
        is_mod_rewrite => 1,
    ...

Optional. Takes either true or false values. If set to a true value, the plugin will assume that you're using Apache's mod_rewrite to rewrite your URIs into a clean form, thusly: /foo?bar=ber to internally become /index.pl?page=/foo&bar=ber. If set to a false value, plugin will create fully blown URIs with index.pl in them. Defaults to: 1

quiet_index

    plug_current_page_uri => {
        quiet_index => 1,
    ...

Optional. Takes either true or false values. If set to a true value, plugin will rename pages called index to empty string. In other words, while normally webroot URI would result in query parameter $q->{page} set to value index and the plugin spitting out the URI as /index; when quiet_index is turned on, the plugin will modify it to / (without the index part). Note: this does NOT modify the value in the query parameters hashref; the change is local to the plugin. Defaults to: 1

HTML::Template VARIABLES

    <tmpl_var escape='html' name='page'>
    <tmpl_var escape='html' name='page_q'>
    <tmpl_var escape='html' name='page_full'>

If current page's URI is http://zcms/?text=lalala and all the defaults are used, the output will be:

    /
    /?text=lalala
    http://zcms/?text=lalala

Plugin adds three variables into {t} ZofCMS Template special key, for you to use in your HTML::Template Template. Below their default names are shown; plugin's argument prefix specifies the string to prepend to these default names. Examples show output when current page's URI is http://zcms/?text=lalala.

page

    <tmpl_var escape='html' name='page'>

    Output: /

This variable will contain the current page's URI relative to web-root and query parameters omitted.

page_q

    <tmpl_var escape='html' name='page_q'>

    Output: /?text=lalala

This variable will contain the current page's URI relative to web-root with all query parameters appended. The query parameters will be escaped using URI::Escape.

page_full

    <tmpl_var escape='html' name='page_full'>

    Output: http://zcms/?text=lalala

This variable will contain the current page's full URI all query parameters appended. Note: this variale will actually be derived from %ENV, thus the query escapes might be less strict as they won't be done by this plugin.

REQUIRED MODULES

This plugin needs URI::Escape version 3.29 or greater.

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