includes/ImageGallery.php

   1 <?php
   2 if ( ! defined( 'MEDIAWIKI' ) )
   3         die( 1 );
   4
   5 /**
   6  */
   7
   8 /**
   9  * Image gallery
  10  *
  11  * Add images to the gallery using add(), then render that list to HTML using toHTML().
  12  *
  13  * @addtogroup Media
  14  */
  15 class ImageGallery
  16 {
  17         var $mImages, $mShowBytes, $mShowFilename;
  18         var $mCaption = false;
  19         var $mSkin = false;
  20         var $mRevisionId = 0;
  21
  22         /**
  23          * Is the gallery on a wiki page (i.e. not a special page)
  24          */
  25         var $mParsing;
  26
  27         /**
  28          * Contextual title, used when images are being screened
  29          * against the bad image list
  30          */
  31         private $contextTitle = false;
  32
  33         private $mPerRow = 4; // How many images wide should the gallery be?
  34         private $mWidths = 120, $mHeights = 120; // How wide/tall each thumbnail should be
  35
  36         private $mAttribs = array();
  37
  38         /**
  39          * Create a new image gallery object.
  40          */
  41         function __construct( ) {
  42                 $this->mImages = array();
  43                 $this->mShowBytes = true;
  44                 $this->mShowFilename = true;
  45                 $this->mParsing = false;
  46         }
  47
  48         /**
  49          * Set the "parse" bit so we know to hide "bad" images
  50          */
  51         function setParsing( $val = true ) {
  52                 $this->mParsing = $val;
  53         }
  54
  55         /**
  56          * Set the caption (as plain text)
  57          *
  58          * @param $caption Caption
  59          */
  60         function setCaption( $caption ) {
  61                 $this->mCaption = htmlspecialchars( $caption );
  62         }
  63
  64         /**
  65          * Set the caption (as HTML)
  66          *
  67          * @param $caption Caption
  68          */
  69         public function setCaptionHtml( $caption ) {
  70                 $this->mCaption = $caption;
  71         }
  72
  73         /**
  74          * Set how many images will be displayed per row.
  75          *
  76          * @param int $num > 0; invalid numbers will be rejected
  77          */
  78         public function setPerRow( $num ) {
  79                 if ($num > 0) {
  80                         $this->mPerRow = (int)$num;
  81                 }
  82         }
  83
  84         /**
  85          * Set how wide each image will be, in pixels.
  86          *
  87          * @param int $num > 0; invalid numbers will be ignored
  88          */
  89         public function setWidths( $num ) {
  90                 if ($num > 0) {
  91                         $this->mWidths = (int)$num;
  92                 }
  93         }
  94
  95         /**
  96          * Set how high each image will be, in pixels.
  97          *
  98          * @param int $num > 0; invalid numbers will be ignored
  99          */
 100         public function setHeights( $num ) {
 101                 if ($num > 0) {
 102                         $this->mHeights = (int)$num;
 103                 }
 104         }
 105
 106         /**
 107          * Instruct the class to use a specific skin for rendering
 108          *
 109          * @param $skin Skin object
 110          */
 111         function useSkin( $skin ) {
 112                 $this->mSkin = $skin;
 113         }
 114
 115         /**
 116          * Return the skin that should be used
 117          *
 118          * @return Skin object
 119          */
 120         function getSkin() {
 121                 if( !$this->mSkin ) {
 122                         global $wgUser;
 123                         $skin = $wgUser->getSkin();
 124                 } else {
 125                         $skin = $this->mSkin;
 126                 }
 127                 return $skin;
 128         }
 129
 130         /**
 131          * Add an image to the gallery.
 132          *
 133          * @param $title Title object of the image that is added to the gallery
 134          * @param $html  String: additional HTML text to be shown. The name and size of the image are always shown.
 135          */
 136         function add( $title, $html='' ) {
 137                 if ( $title instanceof File ) {
 138                         // Old calling convention
 139                         $title = $title->getTitle();
 140                 }
 141                 $this->mImages[] = array( $title, $html );
 142                 wfDebug( "ImageGallery::add " . $title->getText() . "\n" );
 143         }
 144
 145         /**
 146         * Add an image at the beginning of the gallery.
 147         *
 148         * @param $title Title object of the image that is added to the gallery
 149         * @param $html  String:  Additional HTML text to be shown. The name and size of the image are always shown.
 150         */
 151         function insert( $title, $html='' ) {
 152                 if ( $title instanceof File ) {
 153                         // Old calling convention
 154                         $title = $title->getTitle();
 155                 }
 156                 array_unshift( $this->mImages, array( &$title, $html ) );
 157         }
 158
 159
 160         /**
 161          * isEmpty() returns true if the gallery contains no images
 162          */
 163         function isEmpty() {
 164                 return empty( $this->mImages );
 165         }
 166
 167         /**
 168          * Enable/Disable showing of the file size of an image in the gallery.
 169          * Enabled by default.
 170          *
 171          * @param $f Boolean: set to false to disable.
 172          */
 173         function setShowBytes( $f ) {
 174                 $this->mShowBytes = ( $f == true);
 175         }
 176
 177         /**
 178          * Enable/Disable showing of the filename of an image in the gallery.
 179          * Enabled by default.
 180          *
 181          * @param $f Boolean: set to false to disable.
 182          */
 183         function setShowFilename( $f ) {
 184                 $this->mShowFilename = ( $f == true);
 185         }
 186
 187         /**
 188          * Set arbitrary attributes to go on the HTML gallery output element.
 189          * Should be suitable for a &lt;table&gt; element.
 190          *
 191          * Note -- if taking from user input, you should probably run through
 192          * Sanitizer::validateAttributes() first.
 193          *
 194          * @param array of HTML attribute pairs
 195          */
 196         function setAttributes( $attribs ) {
 197                 $this->mAttribs = $attribs;
 198         }
 199
 200         /**
 201          * Return a HTML representation of the image gallery
 202          *
 203          * For each image in the gallery, display
 204          * - a thumbnail
 205          * - the image name
 206          * - the additional text provided when adding the image
 207          * - the size of the image
 208          *
 209          */
 210         function toHTML() {
 211                 global $wgLang;
 212
 213                 $sk = $this->getSkin();
 214
 215                 $attribs = Sanitizer::mergeAttributes(
 216                         array(
 217                                 'class' => 'gallery',
 218                                 'cellspacing' => '0',
 219                                 'cellpadding' => '0' ),
 220                         $this->mAttribs );
 221                 $s = Xml::openElement( 'table', $attribs );
 222                 if( $this->mCaption )
 223                         $s .= "\n\t<caption>{$this->mCaption}</caption>";
 224
 225                 $params = array( 'width' => $this->mWidths, 'height' => $this->mHeights );
 226                 $i = 0;
 227                 foreach ( $this->mImages as $pair ) {
 228                         $nt = $pair[0];
 229                         $text = $pair[1];
 230
 231                         # Give extensions a chance to select the file revision for us
 232                         $time = false;
 233                         wfRunHooks( 'BeforeGalleryFindFile', array( &$this, &$nt, &$time ) );
 234
 235                         $img = wfFindFile( $nt, $time );
 236
 237                         if( $nt->getNamespace() != NS_IMAGE || !$img ) {
 238                                 # We're dealing with a non-image, spit out the name and be done with it.
 239                                 $thumbhtml = "\n\t\t\t".'<div style="height: '.($this->mHeights*1.25+2).'px;">'
 240                                         . htmlspecialchars( $nt->getText() ) . '</div>';
 241                         } elseif( $this->mParsing && wfIsBadImage( $nt->getDBkey(), $this->getContextTitle() ) ) {
 242                                 # The image is blacklisted, just show it as a text link.
 243                                 $thumbhtml = "\n\t\t\t".'<div style="height: '.($this->mHeights*1.25+2).'px;">'
 244                                         . $sk->makeKnownLinkObj( $nt, htmlspecialchars( $nt->getText() ) ) . '</div>';
 245                         } elseif( !( $thumb = $img->transform( $params ) ) ) {
 246                                 # Error generating thumbnail.
 247                                 $thumbhtml = "\n\t\t\t".'<div style="height: '.($this->mHeights*1.25+2).'px;">'
 248                                         . htmlspecialchars( $img->getLastError() ) . '</div>';
 249                         } else {
 250                                 $vpad = floor( ( 1.25*$this->mHeights - $thumb->height ) /2 ) - 2;
 251                                 $thumbhtml = "\n\t\t\t".'<div class="thumb" style="padding: ' . $vpad . 'px 0; width: '.($this->mWidths+30).'px;">'
 252                                         . $sk->makeKnownLinkObj( $nt, $thumb->toHtml() ) . '</div>';
 253                         }
 254
 255                         //TODO
 256                         //$ul = $sk->makeLink( $wgContLang->getNsText( Namespace::getUser() ) . ":{$ut}", $ut );
 257
 258                         if( $this->mShowBytes ) {
 259                                 if( $img ) {
 260                                         $nb = wfMsgExt( 'nbytes', array( 'parsemag', 'escape'),
 261                                                 $wgLang->formatNum( $img->getSize() ) );
 262                                 } else {
 263                                         $nb = wfMsgHtml( 'filemissing' );
 264                                 }
 265                                 $nb = "$nb<br />\n";
 266                         } else {
 267                                 $nb = '';
 268                         }
 269
 270                         $textlink = $this->mShowFilename ?
 271                                 $sk->makeKnownLinkObj( $nt, htmlspecialchars( $wgLang->truncate( $nt->getText(), 20, '...' ) ) ) . "<br />\n" :
 272                                 '' ;
 273
 274                         # ATTENTION: The newline after <div class="gallerytext"> is needed to accommodate htmltidy which
 275                         # in version 4.8.6 generated crackpot html in its absence, see:
 276                         # http://bugzilla.wikimedia.org/show_bug.cgi?id=1765 -Ævar
 277
 278                         if ( $i % $this->mPerRow == 0 ) {
 279                                 $s .= "\n\t<tr>";
 280                         }
 281                         $s .=
 282                                 "\n\t\t" . '<td><div class="gallerybox" style="width: '.($this->mWidths*1.25).'px;">'
 283                                         . $thumbhtml
 284                                         . "\n\t\t\t" . '<div class="gallerytext">' . "\n"
 285                                                 . $textlink . $text . $nb
 286                                         . "\n\t\t\t</div>"
 287                                 . "\n\t\t</div></td>";
 288                         if ( $i % $this->mPerRow == $this->mPerRow - 1 ) {
 289                                 $s .= "\n\t</tr>";
 290                         }
 291                         ++$i;
 292                 }
 293                 if( $i % $this->mPerRow != 0 ) {
 294                         $s .= "\n\t</tr>";
 295                 }
 296                 $s .= "\n</table>";
 297
 298                 return $s;
 299         }
 300
 301         /**
 302          * @return int Number of images in the gallery
 303          */
 304         public function count() {
 305                 return count( $this->mImages );
 306         }
 307
 308         /**
 309          * Set the contextual title
 310          *
 311          * @param Title $title Contextual title
 312          */
 313         public function setContextTitle( $title ) {
 314                 $this->contextTitle = $title;
 315         }
 316
 317         /**
 318          * Get the contextual title, if applicable
 319          *
 320          * @return mixed Title or false
 321          */
 322         public function getContextTitle() {
 323                 return is_object( $this->contextTitle ) && $this->contextTitle instanceof Title
 324                                 ? $this->contextTitle
 325                                 : false;
 326         }
 327
 328 } //class
 329