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