add some documentation for image objects

diff --git a/site/cgi-bin/modules/BSE/ImageHandler/Img.pm b/site/cgi-bin/modules/BSE/ImageHandler/Img.pm
index 5af7591fd6af2d65bb083b318bf5a397c885c38a..3b015818b8efc70f5e786b53116edcd739178f15 100644 (file)
--- a/site/cgi-bin/modules/BSE/ImageHandler/Img.pm
+++ b/site/cgi-bin/modules/BSE/ImageHandler/Img.pm
@@ -4,7 +4,7 @@ use base 'BSE::ImageHandler::Base';
 use Carp qw(confess);
 use BSE::Util::HTML;
 
-our $VERSION = "1.004";
+our $VERSION = "1.005";
 
 sub format {
   my ($self, %opts) = @_;
@@ -167,9 +167,14 @@ sub thumb {
     or return escape_html($error);
   
   if ($field) {
-    my $value = $imwork->{$field};
-    defined $value or $value = '';
-    return escape_html($value);
+    if ($field eq "object") {
+      return $imwork;
+    }
+    else {
+      my $value = $imwork->{$field};
+      defined $value or $value = '';
+      return escape_html($value);
+    }
   }
   else {
     my $class = $cfg->entry('thumb classes', $geo_id, "bse_image_thumb");

diff --git a/site/cgi-bin/modules/BSE/TB/Image.pm b/site/cgi-bin/modules/BSE/TB/Image.pm
index f143455f1a1459774eafba2a439eb7dd6861a5aa..a96d2ac127e16259206b39ac9cc047a279b55398 100644 (file)
--- a/site/cgi-bin/modules/BSE/TB/Image.pm
+++ b/site/cgi-bin/modules/BSE/TB/Image.pm
@@ -8,7 +8,79 @@ use vars qw/@ISA/;
 @ISA = qw/Squirrel::Row BSE::ThumbCommon BSE::TB::TagOwner/;
 use Carp qw(confess);
 
-our $VERSION = "1.007";
+our $VERSION = "1.008";
+
+=head1 NAME
+
+BSE::TB::Image - images attached to an article or a global image.
+
+=head1 SYNOPSIS
+
+  my @images = $article->images;
+
+=head1 DESCRIPTION
+
+X<images>This class represents an image attached to an article, or a
+global image.
+
+=head1 METHODS
+
+=over
+
+=item id
+
+Unique id for this image.
+
+=item articleId
+
+article this image belongs to.  C<-1> for global images.
+
+=item image
+
+image filename as stored in the images directory.  See C</image_url>
+to get a URL to the image.
+
+=item alt
+
+alternate text for the image
+
+=item width
+
+=item height
+
+X<image, width>X<image, height>width and height of the
+image in pixels.
+
+=item url
+
+url to link to when the image is inlined.
+
+=item displayOrder
+
+sort key for ordering images belonging to an article (or within the
+global image collection.)
+
+=item name
+
+unique name for the image within the images belonging to an article
+(or withing the global image collection.)  Can be an empty string.
+
+=item storage
+
+the external storage used for the image, or C<local> for locally
+stored images.
+
+=item src
+
+for externally stored images, the URL to the image.  Use
+C</image_url()>.
+
+=item ftype
+
+the type of image, either C<img> for normal images, or C<flash> for
+flash files.
+
+=cut
 
 sub columns {
   return qw/id articleId image alt width height url displayOrder name
@@ -17,6 +89,28 @@ sub columns {
 
 sub table { "image" }
 
+=item formatted(...)
+
+Call the format() image handler object for this image.
+
+Accepts the following parameters:
+
+=over
+
+=item *
+
+C<align> - sets the align attribute.
+
+=item *
+
+C<extras> - extra C<img> tag attributes.
+
+=back
+
+Returns HTML.
+
+=cut
+
 sub formatted {
   my ($self, %opts) = @_;
 
@@ -32,6 +126,22 @@ sub formatted {
     );
 }
 
+=item inline(...)
+
+Inline the image, accepts the following parameters:
+
+=over
+
+=item *
+
+C<align> - set class to C<< bse_image_I<align> >>.
+
+=back
+
+Returns HTML.
+
+=cut
+
 sub inline {
   my ($self, %opts) = @_;
 
@@ -47,6 +157,30 @@ sub inline {
     );
 }
 
+=item popimage(...)
+
+Call the popimage() image handler object for this image, displaying
+the image as a thumbnail that displays a larger version when clicked.
+
+Parameters:
+
+=over
+
+=item *
+
+C<class> - controls the section of the config file that popup
+parameters are taken from.
+
+=item *
+
+C<static> - true to use static URLs for the thumbnails.
+
+=back
+
+Returns HTML.
+
+=cut
+
 sub popimage {
   my ($im, %opts) = @_;
 
@@ -62,12 +196,26 @@ sub popimage {
     );
 }
 
+=item image_url
+
+Return the image's source URL.  This will be the storage URL if the
+image is C<storage> is not C<local>.
+
+=cut
+
 sub image_url {
   my ($im) = @_;
 
   return $im->src || BSE::TB::Images->base_uri . $im->image;
 }
 
+=item json_data
+
+Returns the image data as a data structure suitable for conversion to
+JSON.
+
+=cut
+
 sub json_data {
   my ($self) = @_;
 
@@ -78,6 +226,22 @@ sub json_data {
   return $data;
 }
 
+=item dynamic_thumb_url(...)
+
+Return a dynamic URL to a thumbnail of the image.
+
+Requires one named parameter:
+
+=over
+
+=item *
+
+C<geo> - the thumbnail geometry to use.
+
+=back
+
+=cut
+
 sub dynamic_thumb_url {
   my ($self, %opts) = @_;
 
@@ -105,6 +269,12 @@ sub filename {
   return $self->image;
 }
 
+=item article
+
+The article this image belongs to.
+
+=cut
+
 sub article {
   my ($self) = @_;
 
@@ -118,6 +288,12 @@ sub article {
   }
 }
 
+=item remove
+
+Remove the image.
+
+=cut
+
 sub remove {
   my ($self) = @_;
 
@@ -126,6 +302,12 @@ sub remove {
   return $self->SUPER::remove();
 }
 
+=item update
+
+Make updates to the image.
+
+=cut
+
 sub update {
   my ($image, %opts) = @_;
 
@@ -290,3 +472,15 @@ sub tableClass {
 }
 
 1;
+
+=back
+
+=head1 INHERITED BEHAVIOUR
+
+Inherits from L<BSE::TB::TagOwner> and L<BSE::ThumbCommon>
+
+=head1 AUTHOR
+
+Tony Cook <tony@develop-help.com>
+
+=cut

diff --git a/site/cgi-bin/modules/BSE/ThumbCommon.pm b/site/cgi-bin/modules/BSE/ThumbCommon.pm
index f74a0e3325e87a289b7d57bc95cfb6f276f5feee..1e38ff4ed3ad8e2c2ce0ab4fb2c36aaf577182b0 100644 (file)
--- a/site/cgi-bin/modules/BSE/ThumbCommon.pm
+++ b/site/cgi-bin/modules/BSE/ThumbCommon.pm
@@ -2,7 +2,21 @@ package BSE::ThumbCommon;
 use strict;
 use Carp ();
 
-our $VERSION = "1.000";
+our $VERSION = "1.001";
+
+=head1 NAME
+
+BSE::ThumbCommon - behaviour for images with thumbnails.
+
+=head1 SYNOPSIS
+
+  my $thumb = $image->thumb(...)
+
+=head1 DESCRIPTION
+
+=over
+
+=cut
 
 # common code between article images and BSE::TB::File
 
@@ -17,6 +31,39 @@ sub _handler_object {
   my $handler = $module->new(cfg => $cfg);
 }
 
+=item thumb(...)
+
+Calls the thumb method on the image handler object.
+
+Parameters:
+
+=over
+
+=item *
+
+C<geo> - thumbnail geometry
+
+=item *
+
+C<field> - field to return, if any.  This can be C<object> to return a
+hash of image information.  Fields are otherwise returned HTML
+encoded.
+
+=item *
+
+C<geo> - thumbnail geometry (required)
+
+=item *
+
+C<static> - set to true to return a URL to a pregenerated thumbnail
+image.
+
+=back
+
+Returns HTML unless C<field> is supplied.
+
+=cut
+
 sub thumb {
   my ($im, %opts) = @_;
 
@@ -32,3 +79,11 @@ sub thumb {
 }
 
 1;
+
+=back
+
+=head1 AUTHOR
+
+Tony Cook <tony@develop-help.com>
+
+=cut