HTML::KhatGallery::Core - the core methods for HTML::KhatGallery
version 0.2405
# implicitly use HTML::KhatGallery qw(HTML::KhatGallery::Core HTML::KhatGallery::Plugin::MyPlugin ...); # or explicitly require HTML::KhatGallery; @plugins = qw(HTML::KhatGallery::Core HTML::KhatGallery::Plugin::MyPlugin ...); HTML::KhatGallery->import(@plugins); HTML::KhatGallery->run(%args);
HTML::KhatGallery is a photo-gallery generator.
HTML::KhatGallery::Core provides the core functionality of the system. Other functions can be added or overridden by plugin modules.
HTML::KhatGallery->run(%args);
run is the only method you should need to use from outside this module; other methods are called internally by this one.
run
This method orchestrates all the work; it creates a new object, and applies all the actions.
Arguments:
The name of the captions file; which is in the same directory as the images which it describes. This file is in YAML format. For example:
--- index.html: this is the caption for the album as a whole image1.png: this is the caption for image1.png image2.jpg: I like the second image
(default: captions.yml)
Instead of generating files, clean up the thumbnail directories to remove thumbnails and image HTML pages for images which are no longer there.
Set the level of debugging output. The higher the level, the more verbose. (developer only) (default: 0)
Regular expression to match the directories we are interested in. Hidden directories and the thumbnail directory will never be included.
Force the re-generation of all the HTML files even if they already exist. If false (the default) then a given HTML file will only be created if there is a change in that particular directory.
Force the re-generation of the thumbnail images even if they already exist. If false (the default) then a given (thumbnail) image file will only be created if it doesn't already exist.
Regular expression determining what filenames should be interpreted as images.
Array reference containing formats for meta-data from the images. Field names are surrounded by % characters. For example:
meta => ['Date: %DateTime%', '%Comment%'],
If an image doesn't have that particular field, the data for that field is not shown. All the meta-data is placed after any caption the image has.
Template for HTML pages. The default template is this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title><!--kg_title--></title> <!--kg_style--> </head> <body> <!--kg_content--> </body> </html>
This can be a string or a filename.
The number of images to display per index page.
The name of the directory where thumbnails and image-pages are put. It is a subdirectory below the directory where its images are. (default: tn)
The size of the thumbnails. This doesn't actually define the dimensions of the thumbnails, but their area. This gives better-quality thumbnails. (default:100x100)
The directory to look for images in; this will be searched for images and sub-directories. If this is not given, the current directory is used.
The directory to create galleries in; HTML and thumbnails will be created there. If this is not given, it is the same as top_dir.
The URL of the top images directory; if the top_out_dir isn't the same as the top_dir, then we need to know this in order to link to the images in the images directory.
Print informational messages.
Only of interest to developers and those wishing to write plugins.
Make a new object. See "run" for the arguments. This method should not be overridden by plugin writers; use "init" instead.
Do some initialization of the object after it's created. See "run" for the arguments. Set up defaults for things which haven't been defined.
Plugin writers should override this method rather than "new" if they want to do some initialization for their plugin.
$self->do_dir_actions($dir);
Do all the actions in the $self->{dir_actions} list, for the given directory. If cleaning, do the actions in the 'clean_actions' list instead. If the dir is empty, this is taken to be the directory given in $self->{top_dir}, the top-level directory.
$self->do_image_actions(\%dir_state, @images);
Do all the actions in the $self->{image_actions} list, for the given images.
Methods implementing directory-related actions. All such actions expect a reference to a state hash, and generally will update either that hash or the object itself, or both, in the course of their running.
Initialize various settings that need to be set before everything else.
This is not the same as "init", because this is the start of the dir_actions sequence; we do it for each directory (or sub-directory) we traverse.
Set the $dir_state->{captions} hash to contain all the captions for this directory (if they exist)
Read the $dir_state->{dir} directory. Sets $dir_state->{subdirs}, and $dir_state->{files} with the relative subdirs, and other files.
Read the $dir_state->{dir} directory in the output tree. Sets $dir_state->{index_files} with the index*.html files.
Sets $dir_state->{files} to contain only image files that we are interested in.
Sorts the $dir_state->{files} array.
Sets $dir_state->{subdirs} to contain only directories that we are interested in.
Sorts the $dir_state->{subdirs} array.
Make the index page(s) for this directory.
Clean unused thumbnails and image-pages from the thumbnail directory of this directory
Process the images from this directory.
Process the sub-directories of this directory.
Cleanup after processing this directory.
Methods implementing per-image actions.
Initialize settings for the current image.
Make a thumbnail of the current image. Constant pixel count among generated images based on http://www.chaosreigns.com/code/thumbnail/
Make HTML page for current image.
Clean up after the current image.
Methods which can be called from within other methods.
push @content, $self->start_index_page($dir_state, $page);
Create the start-of-page for an index page. This contains page content, not full <html> etc (that's expected to be in the full-page template). It contains the header, link to parent dirs and links to previous and next index-pages, and the album caption.
my $links = $self->start_index_page($dir_state, $page);
Make the previous next other-index-pages links for the given index-page. Generally called for the top and bottom of the index page.
push @content, $self->end_index_page($dir_state, $page);
Create the end-of-page for an index page. This contains page content, not full <html> etc (that's expected to be in the full-page template).
push @content, $self->make_index_subdirs($dir_state, $page);
Create the subdirs section; this contains links to subdirs.
push @content, $self->make_image_index(dir_state=>$dir_state, page=>$page, images=>\@images);
Create the images section; this contains links to image-pages, with thumbnails.
Make the title for the index page. This is expected to go inside a <title><!--kg_title--></title> in the page template.
Make the style tags for the index page. This will be put in the <!--kg_style--> part of the template.
my $name = self->get_index_pagename( dir_state=>$dir_state, page=>$page, get_filename=>0);
Get the name of the given index page; either the file name or the relative URL.
my $name = self->get_image_pagename( dir_state=>$dir_state, image=>$image, type=>'file');
Get the name of the image page; either the file name or the relative URL from above, or the relative URL from the sibling, or a 'pretty' name suitable for a title.
The 'type' can be 'file', 'parent', 'sibling' or 'pretty'.
my $name = self->get_thumbnail_name( dir_state=>$dir_state, image=>$image, type=>'file');
Get the name of the image thumbnail file; either the file name or the relative URL from above, or the relative URL from the sibling.
The 'type' can be 'file', 'parent', 'sibling'.
my $name = self->get_caption( dir_state=>$dir_state, img_state->$img_state, image=>$image)
Get the caption for this image. This also gets the meta-data if any is required.
my $templ = $self->get_template($template);
Get the given template (read if it's from a file)
push @content, $self->start_image_page($dir_state, $img_state);
Create the start-of-page for an image page. This contains page content, not full <html> etc (that's expected to be in the full-page template). It contains the header, link to parent dirs and links to previous and next image-pages.
push @content, $self->end_image_page($dir_state, $img_state);
Create the end-of-page for an image page. This contains page content, not full <html> etc (that's expected to be in the full-page template).
my $links = $self->make_image_prev_next( dir_state=>$dir_state, img_state=>$img_state);
Make the previous next other-image-pages links for the given image-page. Generally called for the top and bottom of the image page.
Make the content of the image page, the image itself.
Make the title for the image page. This is expected to go inside a <title><!--kg_title--></title> in the page template.
Make the style tags for the image page. This will be put in the <!--kg_style--> part of the template.
Check if a thumbnail needs to be made (or rebuilt).
Check to see if there are any new (or deleted) images or directories in this directory.
Get the image information for an image. Returns a hash of information.
%info = $self->get_image_info($image_file);
$self->debug($level, $message);
Print a debug message (for debugging). Checks $self->{'debug_level'} to see if the message should be printed or not.
Methods which may or may not be here in future.
For debugging: say who called this
Test::More
To install this module, run the following commands:
perl Build.PL ./Build ./Build test ./Build install
Or, if you're on a platform (like DOS or Windows) that doesn't like the "./" notation, you can do this:
perl Build.PL perl Build perl Build test perl Build install
In order to install somewhere other than the default, such as in a directory under your home directory, like "/home/fred/perl" go
perl Build.PL --install_base /home/fred/perl
as the first step instead.
This will install the files underneath /home/fred/perl.
You will then need to make sure that you alter the PERL5LIB variable to find the modules, and the PATH variable to find the script.
Therefore you will need to change: your path, to include /home/fred/perl/script (where the script will be)
PATH=/home/fred/perl/script:${PATH}
the PERL5LIB variable to add /home/fred/perl/lib
PERL5LIB=/home/fred/perl/lib:${PERL5LIB}
perl(1).
Please report any bugs or feature requests to the author.
Kathryn Andersen (RUBYKAT) perlkat AT katspace dot com http://www.katspace.org/tools
Copyright (c) 2006 by Kathryn Andersen
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install HTML::KhatGallery, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::KhatGallery
CPAN shell
perl -MCPAN -e shell install HTML::KhatGallery
For more information on module installation, please visit the detailed CPAN module installation guide.