/ 
khatgallery-0.2405
River stage zero No dependents
/ HTML::KhatGallery::Core

NAME

HTML::KhatGallery::Core - the core methods for HTML::KhatGallery

VERSION

version 0.2405

SYNOPSIS

# 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);

DESCRIPTION

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.

CLASS METHODS

run

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.

This method orchestrates all the work; it creates a new object, and applies all the actions.

Arguments:

captions_file

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)

clean

Instead of generating files, clean up the thumbnail directories to remove thumbnails and image HTML pages for images which are no longer there.

debug_level

Set the level of debugging output. The higher the level, the more verbose. (developer only) (default: 0)

dir_match

Regular expression to match the directories we are interested in. Hidden directories and the thumbnail directory will never be included.

force_html

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_images

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.

image_match

Regular expression determining what filenames should be interpreted as images.

meta

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.

page_template

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.

per_page

The number of images to display per index page.

thumbdir

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)

thumb_geom

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)

top_dir

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.

top_out_dir

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.

top_url

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.

verbose

Print informational messages.

OBJECT METHODS

Only of interest to developers and those wishing to write plugins.

new

Make a new object. See "run" for the arguments. This method should not be overridden by plugin writers; use "init" instead.

init

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.

do_dir_actions

$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.

do_image_actions

$self->do_image_actions(\%dir_state, @images);

Do all the actions in the $self->{image_actions} list, for the given images.

Dir Action Methods

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.

init_settings

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.

read_captions

Set the $dir_state->{captions} hash to contain all the captions for this directory (if they exist)

read_dir

Read the $dir_state->{dir} directory. Sets $dir_state->{subdirs}, and $dir_state->{files} with the relative subdirs, and other files.

read_out_dir

Read the $dir_state->{dir} directory in the output tree. Sets $dir_state->{index_files} with the index*.html files.

filter_images

Sets $dir_state->{files} to contain only image files that we are interested in.

sort_images

Sorts the $dir_state->{files} array.

filter_dirs

Sets $dir_state->{subdirs} to contain only directories that we are interested in.

sort_dirs

Sorts the $dir_state->{subdirs} array.

make_index_page

Make the index page(s) for this directory.

clean_thumb_dir

Clean unused thumbnails and image-pages from the thumbnail directory of this directory

process_images

Process the images from this directory.

process_subdirs

Process the sub-directories of this directory.

tidy_up

Cleanup after processing this directory.

Image Action Methods

Methods implementing per-image actions.

init_image_settings

Initialize settings for the current image.

make_thumbnail

Make a thumbnail of the current image. Constant pixel count among generated images based on http://www.chaosreigns.com/code/thumbnail/

make_image_page

Make HTML page for current image.

image_tidy_up

Clean up after the current image.

Helper Methods

Methods which can be called from within other methods.

start_index_page

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.

make_index_prev_next

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.

end_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).

make_index_subdirs

push @content, $self->make_index_subdirs($dir_state, $page);

Create the subdirs section; this contains links to subdirs.

make_image_index

    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_index_title

Make the title for the index page. This is expected to go inside a <title><!--kg_title--></title> in the page template.

make_index_style

Make the style tags for the index page. This will be put in the <!--kg_style--> part of the template.

get_index_pagename

    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.

get_image_pagename

    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'.

get_thumbnail_name

    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'.

get_caption

    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.

get_template

my $templ = $self->get_template($template);

Get the given template (read if it's from a file)

start_image_page

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.

end_image_page

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).

make_image_prev_next

    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_image_content

Make the content of the image page, the image itself.

make_image_title

Make the title for the image page. This is expected to go inside a <title><!--kg_title--></title> in the page template.

make_image_style

Make the style tags for the image page. This will be put in the <!--kg_style--> part of the template.

need_to_generate_image

Check if a thumbnail needs to be made (or rebuilt).

index_needs_rebuilding

Check to see if there are any new (or deleted) images or directories in this directory.

get_image_info

Get the image information for an image. Returns a hash of information.

%info = $self->get_image_info($image_file);

debug

$self->debug($level, $message);

Print a debug message (for debugging). Checks $self->{'debug_level'} to see if the message should be printed or not.

Private Methods

Methods which may or may not be here in future.

_whowasi

For debugging: say who called this

REQUIRES

Test::More

INSTALLATION

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}

SEE ALSO

perl(1).

BUGS

Please report any bugs or feature requests to the author.

AUTHOR

Kathryn Andersen (RUBYKAT)
perlkat AT katspace dot com
http://www.katspace.org/tools

COPYRIGHT AND LICENCE

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.