<!--
=head1 NAME

thumbnail.wmk - photo-album style ''thumbnail'' links to images

=head1 LOADING

  < use plugin="thumbnail_tag" />

=head1 HTML TAGS

  < thumbnail name="filename.jpg" [text="template"]
  	[bordercolor="black"] [borderwidth="1"] [format="jpg"] />

=head1 PERL CODE

  <{perl

    make_thumbnail_table (3, @names_of_images);

  }>

=head1 DESCRIPTION

This WebMake Perl library provides a quick shortcut to make thumbnail links to
full-sized images, suitable for use in a photo album site or similar.

The library provides support for a < thumbnail > tag, which creates a thumbnail
of one image, and some helper functions for creating thumbnail pages with lots
of images.

The attributes supported by the < thumbnail > tag are as follows:

=over 4

=item name="imagename"

The image to link to.  This should be the name of a URL reference, loaded from
a < media > search, B<not> the filename of the image itself.

=item borderwidth="n"

If you wish to draw a border around the images, this specifies the border width
(in pixels).  The default value is 1.  This can also be specified by setting
a template content item called C<thumbnail.borderwidth>.

=item bordercolor="#xxxxxx"

The border colour to draw image borders in. The default value is "black" (or
C<#000000>).  This can also be specified by setting a template content item
called C<thumbnail.bordercolor>.

=item format="fmt"

The format to use for thumbnail images; default is "jpg".  Also available:
"gif" or "png".  Any reasonable ImageMagick-supported format will work.

=item text="template"

The template text to be used for the thumbnail link and img tags.  The
following content items are defined for use inside the template text. This can
also be specified by setting a template content item called
C<thumbnail.template>.

=over 4

=item thumbnail.name

The name of the image (not the filename, the < media > item name).

=item thumbnail.path

The image file's path, with directories.

=item thumbnail.filename

The image file's name, without directories.

=item thumbnail.href

The path to the full-sized image file, relative to the current output
file.

=item thumbnail.thumb_src

The path to the thumbnail-sized version of the image file, relative to the
current output file.

=item thumbnail.size_in_k

The full-sized image file's size, in kilobytes (rounded up).

=item thumbnail.size

The full-sized image file's size, in bytes.

=item thumbnail.full_height / thumbnail.full_width

The full-sized image file's height and width, in pixels.

=item thumbnail.height / thumbnail.width

The thumbnail-sized image file's height and width, in pixels.

=item thumbnail.tag_attrs

The remaining attributes of the thumbnail tag.

=back

C<template> can be, and should often be, a $ {content_reference}.  The default
template is:

=over 4

	< div align=center >
	  < a href="$ {thumbnail.href}" >< img
	      src="$ {thumbnail.thumb_src}" alt="[$ {thumbnail.filename}]"
	      height="$ {thumbnail.height}" width="$ {thumbnail.width}"
	      border="0" $ {thumbnail.tag_attrs} / >< /a >
	  < br / >
	  $ [$ {thumbnail.name}.title]
	  < br / >
	< /div >

=back

Note that this means that any unrecognised attributes of the thumbnail tag
itself will become attributes of the IMG tag.

=back

=head1 PERL FUNCTIONS

The following Perl functions are provided:

=over 4

=item $text = make_thumbnail_table ($pics_per_row, @names_of_images);

This function will lay out a table containing thumbnails, with up to
C<$pics_per_row> pictures on each row.  The following template content items
can be set to customise the behaviour of this tag:

=over 4

=item C<$ {thumbnail.table.td}>

The template used to wrap each thumbnail.  References to $
{thumbnail.table.item} will be replaced with the output from the < thumbnail >
tag itself. Default setting:

	< td valign=top > $ {thumbnail.table.item} < /td >

=item C<$ {thumbnail.table.tr}>

The template used to wrap each row of thumbnails.  References to $
{thumbnail.table.tds} will be replaced with the output from the $
{thumbnail.table.td} templates so far for this row.  Default setting:

	< tr > $ {thumbnail.table.tds} < /tr >

=back

Note that you will have to wrap this up in a < table > tag yourself ;)

=back

=head1 EXAMPLES

The file C<examples/thumbnails.wmk> in the WebMake distribution.

=head1 OPTIONS WHICH AFFECT THIS TAG

C<FileSearchPath> - WebMake option

=cut

-->

<{perl

  use HTML::WebMake::PerlLib::ThumbnailTag;

  $self->define_empty_tag ("thumbnail",
  	\&HTML::WebMake::PerlLib::ThumbnailTag::handle_thumbnail_tag,
	qw(name));

  sub make_thumbnail_table {
    my ($rowsize, @imagelist) = @_;

    my @rows = ();
    my @columns = ();
    my $count = 0;

    $rowsize ||= 1;

    foreach my $img (@imagelist) {
      set_content ("thumbnail.table.item",
	      '<thumbnail name="'.$img.'" />');
      push (@columns, get_content ("thumbnail.table.td"));

      if ((++$count) % $rowsize == 0) {
	set_content ("thumbnail.table.tds", join ('', @columns));
	push (@rows, get_content ("thumbnail.table.tr"));
	@columns = ();
      }
    }

    set_content ("thumbnail.table.tds", join ('', @columns));
    push (@rows, get_content ("thumbnail.table.tr"));
    return join ('', @rows);
  }

  ''

}>

<!-- set up some default templates -->

<template name="thumbnail.template">
	<div align=center>
	  <a href="${thumbnail.href}"><img
	      src="${thumbnail.thumb_src}" alt="[${thumbnail.filename}]"
	      height="${thumbnail.height}" width="${thumbnail.width}"
	      border="0" ${thumbnail.tag_attrs} /></a>
	  <br />
	  $[${thumbnail.name}.title]
	  <br />
	</div>
</template>

<template name="thumbnail.table.td">
        <td valign=top> ${thumbnail.table.item} </td>
</template>

<template name="thumbnail.table.tr">
        <tr> ${thumbnail.table.tds} </tr>
</template>