Gallery2:Modules:imageblock - Gallery Codex
Personal tools


From Gallery Codex

Image Block Module

Makes blocks available to themes for showing random/recent/most-viewed images or albums.


Show random images or the highlight of the most viewed album or choose between a lot of other image block types to show in a specific album or on all of your Gallery pages. Or show these images on other websites with the external image block.


  • Choose between different types of image blocks: random image, recent image, most viewed image, random album highlight, recent album highlight, most viewed album, daily image (changes one time each day), weekly image (changes one time each week), monthly image (changes one time each month), daily album highlight, weekly album highlight, monthly album highlight
  • Add multiple image blocks
  • Configure whether to show the title, date, the view counters, ... for each image block
  • Additionally, you can choose to show a specific item defined by itemId if you add the block manually in your theme template (theme.tpl, album.tpl, photo.tpl) or if you use the external image block
  • Show (random) images of your Gallery on other websites or other pages of your website with the external imageblock
  • Limit the item selection to the subtree of the Gallery under the album with the given id (only available for manually added image blocks in your template or in external image blocks)
  • Choose a maximum displayed size for the block
  • Display full sized images


  • Download the module from the download page if necessary. The minimal and typical package of G2 don't include this module.
  • Install and activate the module in site admin -> plugins
  • Configure some settings in site admin -> Image Blocks
  • Add image blocks to your sidebar in site admin -> themes -> matrix (or for any other active/used theme)
  • You can configure each image block separately: See How to Setup Image Blocks
  • Now you and the visitors of your site see the image blocks in your sidebar in all album / photo pages.

Also see:

External Options

The following options are available:

blocks       Pipe(|) separate list chosen from:
               randomImage, recentImage, viewedImage, randomAlbum, recentAlbum,
               viewedAlbum, dailyImage, weeklyImage, monthlyImage, dailyAlbum,
               weeklyAlbum, monthlyAlbum, specificItem; default is randomImage
show         Pipe(|) separated list chosen from:
               title, date, views, owner, heading, fullSize, rawImage, none
itemId       Limit the item selection to the subtree of the gallery under the album with the given id;
               or the id of the item to display when used with specificItem block type
maxSize      Scale images to this maximum size. If used alone Gallery will locate the most-closely-sized
               image to the specified value - larger images will be scaled down as necessary in your browser.
               If specified along with g2_show=fullSize the full size image will always be used and scaled down as necessary.
exactSize    Just like g2_maxSize except that it will not substitute an image smaller than the size you request,
               so you'll get the closest match in size possible. Note that this may use a lot more bandwidth if a much larger
               image has to be scaled down in your browser.
link         Href for link on image; value of none for no link; default is link to item in the Gallery
linkTarget   Add a link target (for example, to open links in a new browser window)

The maxSize and exactSize parameters may need clarification:

  • maxSize - Specifying the maxSize parameter for an external image block attempts to intelligently determine the best-sized image to be placed and fill the block. This was added as a feature to help keep bandwidth usage down for both users and administrators, and to return something that is close to the requested size. Previously (and currently, when specified in this fashion) the only use of maxSize was with the fullSize view option. This yielded gigantic images being returned, but downsized by the browser to fit the size specified by maxSize. Now, the maxSize parameter can be used separately from the fullSize view option.
Example Image:
    100px thumbnail
    500px resize
    1024px original

maxSize Parameter:
    maxSize=299 returns the 100px thumbnail because it is the 
       "closest" in size to the requested maxSize. (199px away, whereas 
       the 500px image is 201px away)

    maxSize=300 returns the 500px resize because in the case 
       of an image having two sizes that are equally close in size 
       (both 200px away) the larger of the two is returned for quality

    maxSize=800 returns the 1024px original
  • exactSize - Just like maxSize except that the image returned will be guaranteed to be downsampled from the next larger size. This means that you'll never get back an image smaller than the dimensions you specify, except in the case where you specify a dimension larger than the original itself.
Example Image:
    100px thumbnail
    500px resize
    1024px original

exactSize Parameter:
    exactSize=299 returns the 500px resize because it is the
       closest larger image.

    exactSize=500 returns the 500px resize because it is an exact

    exactSize=800 (and anything larger) returns the 1024px original

NOTE: Until very recent versions of this module, the "exactSize" parameter did not exist and the "maxSize" parameter did not function as described above.

I am not certain, but I _believe_ the documents above apply to version 1.0.11 (which works with Gallery 2.2 RC1) and not to the version of the module that comes with Gallery 2.1.2.


Display images horizontally. Add: {float: left;} a { display:inline;} img { display:inline;}
    block-imageblock-ImageBlock { display:inline;}

to the css of the theme you are using.

Display a 4x4 grid of recent images, images set to a max size of 50, in a template:

  .one-image {
     display: inline;
  .g2imageblock {
     width: 106px;
   <div class="g2imageblock">
   {g->block type="imageblock.ImageBlock" blocks="recentImage|recentImage|recentImage|recentImage" maxSize=50}

Adjust the .g2imageblock css width if you are using a larger maxSize.

Permissions, Authorizations, and Password-Protected Items

The image block module checks permissions first. This means that a user can only see albums or images in the image block for which he/she has sufficient authorization. If an album is password-protected using the password module, items inside the album will not be shown in the image block (unless the user is the owner of the album). However, the album itself will be shown in the image block. Images or other items that are password-protected directly will also be shown in the image block with their thumbnails. If the user navigates to one of these password-protected albums or items, he/she will be asked for a password.

To exclude password-protected albums and items from the image block completely, the following coding needs to be added to the file gallery2/modules/imageblock/classes/ImageBlockHelper.class before this statement.

list ($ret, $owner) = GalleryCoreApi::loadEntitiesById($item->getOwnerId());

Coding to be added:

//check if the item is directly protected by a password.
//in this case, do not show it in the image block, not even as a preview:
if( $item->hasOnLoadHandler('Password') ){

Requested Features

Currently there are no feature requests for this module.


Currently there are no known issues for this module.