NAME

App::ZofCMS::Plugin::DirTreeBrowse - plugin to display browseable directory tree

SYNOPSIS

SIMPLE VARIANT

In your Main Config file or ZofCMS Template:

    plugins     => [ qw/DirTreeBrowse/ ],
    plug_dir_tree => {
        auto_html => 1,
        start     => 'pics',
    },

In you HTML::Template template:

    <p>We are at: <tmpl_var escape='html' name='dir_tree_path'></p>
    <tmpl_var name='dir_tree_auto'>

MORE FLEXIBLE VARIANT

In your Main Config file or ZofCMS Template:

    plugins     => [ qw/DirTreeBrowse/ ],
    plug_dir_tree => {
        start     => 'pics',
    },

In your HTML::Template template:

    <p>We are at: <tmpl_var escape='html' name='dir_tree_path'></p>

    <ul>
        <tmpl_if name="dir_tree_back">
            <li><a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='dir_tree_back'>">UP</a></li>
        </tmpl_if>
    <tmpl_loop name='dir_tree_list'>
        <li>
            <tmpl_if name="is_file">
            <a href="/<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
            <tmpl_else>
            <a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
            </tmpl_if>
        </li>
    </tmpl_loop>
    </ul>

DESCRIPTION

The module is an App::ZofCMS plugin that provides means to display a browseable directory three (list of files and other dirs).

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

MAIN CONFIG FILE AND ZofCMS TEMPLATE FIRST-LEVEL KEYS

plugins

    plugins => [ qw/DirTreeBrowse/ ],

First and foremost, you'd obviously would want to add the plugin into the list of plugins to execute.

plug_dir_tree

    plug_dir_tree => {
        start                  => 'pics',
        auto_html              => 'ul_class',
        re                     => qr/[.]jpg$/,
        q_name                 => 'dir_tree',
        t_prefix               => 'dir_tree_',
        display_path_separator => '/',
    }

    plug_dir_tree => sub {
        my ( $t, $q, $config ) = @_;
        return {
            start                  => 'pics',
            auto_html              => 'ul_class',
            re                     => qr/[.]jpg$/,
            q_name                 => 'dir_tree',
            t_prefix               => 'dir_tree_',
            display_path_separator => '/',
        };
    }

The plug_dir_tree takes a hashref or subref as a value and can be set in either Main Config file or ZofCMS Template file. Keys that are set in both Main Config file and ZofCMS Template file will get their values from ZofCMS Template file. If subref is specified, its return value will be assigned to plug_dir_tree as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Tempalate hashref, query parameters hashref and App::ZofCMS::Config object. Possible keys/values of plug_dir_tree hashref are as follows:

start

    plug_dir_tree => {
        start => 'pics',
    },

Mandatory. Specifies the starting directory of the directory three you wish to browse. The directory is relative to your index.pl file and must be web-accessible.

auto_html

    plug_dir_tree => {
        start       => 'pics',
        auto_html   => 'ul_class',
    },

Optional. When set to a defined value will cause the plugin to generate directory tree HTML automatically, the value then will become the classname for the <ul> element that holds the list of files/dirs. See SYNOPSIS and HTML::Template VARIABLES sectons for more details. Note: the plugin does not append current query to links, so if you wish to add something to the query parameters

re

    plug_dir_tree => {
        start => 'pics',
        re    => qr/[.]jpg$/,
    }

Optional. Takes a regex (qr//) as a value. When specified only the files matching this regex will be in the list. Note that file and its path will be matched, e.g. pics/old_pics/foo.jpg

q_name

    plug_dir_tree => {
        start  => 'pics',
        q_name => 'dir_tree',
    }

Optional. The plugin uses one query parameter to reference its position in the directory tree. The q_name key specifies the name of that query parameter. Unless you are using the auto_html option, make sure that your links include this query parameter along with <tmpl_var name="path">. In other words, if your q_name is set to dir_tree you'd make your links: <a href="/index.pl?page=/page_with_this_plugin&dir_tree=<tmpl_var escape='html' name='path'>">. Defaults to: dir_tree

t_prefix

    plug_dir_tree => {
        start    => 'pics',
        t_prefix => 'dir_tree_',
    }

Optional. The t_prefix specifies the prefix to use for several keys that plugin creates in {t} ZofCMS Template special key. See HTML::Template VARIABLES section below for details. Defaults to: dir_tree_ (note the trailing underscore (_))

display_path_separator

    plug_dir_tree => {
        start                  => 'pics',
        display_path_separator => '/',
    }

Optional. One of the {t} keys generated by the plugin will contain the current path in the directory tree. If display_path_separator is specified, every / character in that current path will be replaced by whatever display_path_separator is set to. By default is not specified.

HTML::Template VARIABLES

The samples below assume that the plugin is run with all of its optional arguments set to defaults.

When auto_html is turned on

    <p>We are at: <tmpl_var escape='html' name='dir_tree_path'></p>
    <tmpl_var name='dir_tree_auto'>

dir_tree_path

    <p>We are at: <tmpl_var escape='html' name='dir_tree_path'></p>

The <tmpl_var name='dir_three_path'> variable will contain the current path in the directory tree.

dir_tree_auto

    <tmpl_var name='dir_tree_auto'>

The <tmpl_var name='dir_tree_auto'> is available when auto_html option is turned on in the plugin. The generated HTML code would be pretty much as the MORE FLEXIBLE VARIANT section in SYNOPSIS demonstrates.

When auto_html is turned off

    <p>We are at: <tmpl_var escape='html' name='dir_tree_path'></p>
    <ul>
        <tmpl_if name="dir_tree_back">
            <li><a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='dir_tree_back'>">UP</a></li>
        </tmpl_if>
    <tmpl_loop name='dir_tree_list'>
        <li>
            <tmpl_if name="is_file">
            <a href="/<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
            <tmpl_else>
            <a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
            </tmpl_if>
        </li>
    </tmpl_loop>
    </ul>

dir_tree_path

    <p>We are at: <tmpl_var escape='html' name='dir_tree_path'></p>

The <tmpl_var name='dir_three_path'> variable will contain the current path in the directory tree.

dir_tree_back

    <tmpl_if name="dir_tree_back">
        <li><a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='dir_tree_back'>">UP</a></li>
    </tmpl_if>

The dir_tree_back will be available when the user browsed to some directory inside the start directory. It will contain the path to the parent directory so the user could traverse up the tree.

dir_tree_list

    <tmpl_loop name='dir_tree_list'>
        <li>
            <tmpl_if name="is_file">
            <a href="/<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
            <tmpl_else>
            <a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
            </tmpl_if>
        </li>
    </tmpl_loop>

The dir_tree_list will contain data structure suitable for <tmpl_loop name="">. Each item of that loop would be an individual file or a directory. The variables that are available in that loop are as follows:

is_file

    <tmpl_if name="is_file">
        <a target="_blank" href="/<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
    <tmpl_else>
        <a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>
    </tmpl_if>

The is_file will be set whenever the item is a file (as opposed to being a directory). As the example above shows, you'd use this variable as a <tmpl_if name=""> to adjust your links to open the file instead of trying to make the plugin "browse" that file as a directory.

path

    <a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>

The path variable will contain the path to the directory/file (including the name of that directory/file) starting from the start directory. You'd want to include that as a value of q_name query parameter so the user could traverse the dirs.

name

    <a href="/index.pl?page=/&dir_tree=<tmpl_var escape='html' name='path'>"><tmpl_var escape='html' name='name'></a>

The name variable will contain just the name of the file/directory without it's path. You'd want to use this for for displaying the names of the files/dirs to the user.

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