/ 
App-ZofCMS-Plugin-CurrentPageURI-0.0102
/ App::ZofCMS::Plugin::CurrentPageURI

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.

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/, http://mind-power-book.com/)

BUGS

Please report any bugs or feature requests to bug-app-zofcms-plugin-currentpageuri at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-CurrentPageURI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::ZofCMS::Plugin::CurrentPageURI

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 Zoffix Znet.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.