App::ZofCMS::Plugin::FileTypeIcon - present users with pretty icons depending on file type
# first of all, get icon images (they are also in the examples/ dir of this distro)
wget http://zoffix.com/new/fileicons.tar.gz;tar -xvvf fileicons.tar.gz;rm fileicons.tar.gz;
In your ZofCMS Template or Main Config File:
plug_file_type_icon => { files => [ # mandatory qw/ foo.png bar.doc beer.pdf /, sub { my ( $t, $q, $conf ) = @_; return 'meow.wmv'; }, ], # all the defaults for reference: resource => 'pics/fileicons/', prefix => 'fileicon_', as_arrayref => 0, # put all files into an arrayref at $t->{t}{ $prefix } only_path => 0, # i.e. do not generate the <img> element icon_width => 16, icon_height => 16, code_after => sub { my ( $t, $q, $conf ) = @_; die "Weeee"; }, xhtml => 0, },
In your HTML::Template file:
<tmpl_var name='fileicon_0'> <tmpl_var name='fileicon_1'> <tmpl_var name='fileicon_2'> <tmpl_var name='fileicon_3'>
The module is a plugin for App::ZofCMS that provides a method to show pretty little icons that vary depending on the extension of the file (which is just a string as far as the module is concerned).
This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template
There are 69 icons plus the "unknown file" icon in an archive that is in examples/ directory of this distribution. You can also get it from my website:
wget http://zoffix.com/new/fileicons.tar.gz; tar -xvvf fileicons.tar.gz; rm fileicons.tar.gz;
As well as the original website from where I got them: http://www.splitbrain.org/projects/file_icons
Alternatively, you may want to draw your own icons; in that case, the filenames for the icons are made out as $lowercase_filetype_extension.png. If you draw some icons yourself and would like to share, feel free to email them to me at zoffix@cpan.org.
$lowercase_filetype_extension.png
zoffix@cpan.org
These images would obviously need to be placed in web-accessible directory on your website.
plugins
plugins => [ qw/FileTypeIcon/ ],
You obviously need to include the plugin in the list of plugins to execute. You're likely to use this plugin with some other plugins, so make sure to get priority right.
plug_file_type_icon
plug_file_type_icon => { files => [ # mandatory qw/ foo.png bar.doc beer.pdf /, sub { my ( $t, $q, $conf ) = @_; return 'meow.wmv'; }, ], # all the defaults for reference: resource => 'pics/fileicons/', prefix => 'fileicon_', as_arrayref => 0, # put all files into an arrayref at $t->{t}{ $prefix } only_path => 0, # i.e. do not generate the <img> element icon_width => 16, icon_height => 16, code_after => sub { my ( $t, $q, $conf ) = @_; die "Weeee"; }, xhtml => 0, }, # or set config via a subref plug_file_type_icon => sub { my ( $t, $q, $config ) = @_; return { files => [ qw/ foo.png bar.doc beer.pdf /, ], }; },
Plugin won't run if plug_file_type_icon is not set or its files key does not contain any files. The plug_file_type_icon first-level key takes a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_file_type_icon 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. The keys of this hashref can be set in either ZofCMS Template or Main Config Files; keys that are set in both files will take their values from ZofCMS Template file. The following keys/values are valid in plug_file_type_icon:
files
undef
@_
files => [ qw/ foo.png bar.doc beer.pdf /, { 'beer.doc' => 'doc_file' }, sub { my ( $t, $q, $conf ) = @_; return 'meow.wmv'; }, ],
Mandatory. The files key takes either an arrayref, a subref or a hashref as a value. If its value is NOT an arrayref, then it will be converted to an arrayref with just one element - the original value.
The elements of files arrayref can be strings, hashrefs or subrefs. If the value is a subref, the sub will be executed and its return value will replace the subref. The @_ of the sub will contain $t, $q, $conf (in that order) where $t is ZofCMS Template hashref, $q is a hashref of query parameters and $conf is App::ZofCMS::Config object.
$t, $q, $conf
$t
$q
$conf
If the element is a hashref, it must contain only one key/value pair and the key will be treated as a filename to process and the value will become the name of the key in t ZofCMS special key (see prefix key below). If the element is a regular string, then it will be treated as a filename to process.
t
prefix
resource
resource => 'pics/fileicons/',
Optional. Specifies the path to directory with icon images. Must be relative to index.pl file and web-accessible, as this path will be used in generating path/filenames to the icons. Defaults to: pics/fileicons/
index.pl
pics/fileicons/
prefix => 'fileicon_',
Optional. When the plugin generates path to the icon or the <img> element, it will stick it into t ZofCMS special key. The prefix key takes a string as a value and specifies the prefix to use for keys in t ZofCMS special key. If as_arrayref key (see below) is set to a true value, then prefix will specify the name of the key, in t ZofCMS special key where to store that arrayref. When the element of files arrayref is a hashref, the value of the only key in that hashref will become the name of the key in t special key WITHOUT the prefix; otherwise, the name will be constructed by using prefix and a counter; the elements of files arrayref that are hashrefs do not increase that counter. Defaults to: fileicon_ (note that underscore at the end)
<img>
as_arrayref
fileicon_
as_arrayref => 0,
Optional. Takes either true or false values. When set to a true value, the plugin will create an arrayref of generated <img> elements (or just paths) and stick it in t special key under prefix (see above) key. Defaults to: 0
0
only_path
only_path => 0,
Optional. Takes either true or false values. When set to a true value, the plugin will not generate the code for <img> elements, but instead it will only provide paths to appropriate icon image. Defaults to: 0
icon_width
icon_height
icon_width => 16, icon_height => 16,
Optional. All the icon images to which I referred you above are sized 16px x 16px. If you are creating your own icons, use icon_width and icon_height keys to set proper dimensions. You cannot set different sizes for individual icons, but you can use Image::Size in the code_after sub (see below). Defaults to: 16 (for both)
Image::Size
code_after
16
code_after => sub { my ( $t, $q, $conf ) = @_; die "Weeee"; },
Optional. Takes a subref as a value, this subref will be run after all filenames in files arrayref have been processed. The @_ will contain (in that order) $t, $q, $conf where $t is ZofCMS Template hashref, $q is hashref of query parameters and $conf is App::ZofCMS::Config object. By defaults: is not specified.
xhtml
xhtml => 0,
Optional. If you wish to close <img> elements as to when you're writing XHTML, then set xhtml argument to a true value. Defaults to: 0
The plugin generates the following HTML code:
<img class="file_type_icon" src="pics/fileicons/png.png" width="16" height="16" alt="PNG file" title="PNG file">
Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS
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
bug-App-ZofCMS at rt.cpan.org
Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)
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.
LICENSE
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.