---
title: GalleryHandler
inMenu: true
template: /plugin.template
plugin: File/GalleryHandler
---
h2(#description). Description


This file handler uses image gallery files to automatically build image galleries. These image
galleries are highly configurable and theme-able through the use of different gallery styles - have
a look at the <a href="{relocatable: /examples/gallery_styles}">examples section</a>!


h2(#structure). Structure of image galleries


An image gallery consists of three types of page files:

* *image pages*: An image page is created for each image. Normally the title, the unresized image,
   the image description and possible other information as well as navigational links (link to the
   next/previous image etc.) are displayed.
* *gallery pages*: A gallery page displays a list of images (number of images per gallery page is
   customizable). If more images than the maximum number of images per gallery page exist, then two
   or more gallery pages are created.
* *main page*: A main page is only created if two or more gallery pages exist and is used for
   displaying links to the gallery pages.

All these pages are created automatically by the gallery handler, but they don't have any content;
everything is done by the templates of a gallery style. The parameters {param:
File/GalleryHandler:imagePageTemplate}, {param: File/GalleryHandler:galleryPageTemplate} and {param:
File/GalleryHandler:mainPageTemplate} define which templates should be used for image pages, gallery
pages and the main page. The default values can be overwritten in the gallery file!


h2(#gallery-styles). Gallery styles


Gallery styles are used... to style image galleries ;-) A gallery style consists of templates and,
optionally, plugins. A minimal gallery style consists of the following files:

* @gallery_image.template@
* @gallery_gallery.template@
* @gallery_main.template@

To display all available gallery styles use the following command:

<pre>
$ wegben help use gallery_style
</pre>

To use a specific gallery style called STYLE issue the following command:

<pre>
$ wegben use gallery_style STYLE
</pre>

This copies all normal gallery style files from the gallery style to the source directory and all
plugins to the plugin directory, maybe overwritting files (you are asked before copying if you would
like to procede). However, this command is not able to delete previously copied gallery style files,
so you have to remove them yourself.

For information about how a gallery style can be created have a look at
<a href="{relocatable: /documentation/extending_webgen.page}">extending webgen section</a>!


h2(#file-format). Gallery File Format


A gallery file has YAML as file format and is easy to create. It consists of two sections which are
separated by a line consisting only of three dashes: the configuration section and the image
section.


h3(#file-format-config-sec). The configuration section


The first section of a gallery file is the configuration section in which you define the basic
properties of your image gallery like the title or how many images should be displayed per page. By
using the name of a gallery handler parameter as key you can override its value. Additionally the
following keys are used by the gallery handler:

* *title*: The title of the gallery. If this key is not specified, the capitalized file name is used.
* *mainPageMetaInfo*: Used for setting additional meta information for the main page.
* *galleryPagesMetaInfo*: Used for setting additional meta information for the gallery pages.
* *layouter*: Plugin used for additional gallery tasks, has to be registered under
  @GalleryLayouter/&lt;layouter-name&gt;@
* *thumbnailSize*: The size of the thumbnails, can also be set individually for each image.
* *thumbnailResizeMethod*: The method used for creating the thumbnails, can also be set individually
  for each image.

For more information about the last two items have a look at {plugin: File/ThumbnailWriter}!

Two nearly always specified parameters should also be mentioned here: {param:
File/GalleryHandler:imagesPerPage} and {param: File/GalleryHandler:images}. The first specifies how
many images should be placed on a single gallery page. The second one specifies which images should
be used the whole image gallery. These images have to be somewhere in the website source directory!
You can/should not specify images outside the source directory as these images are not automatically
copied to the output directory and automatic thumbnail creation may not work correctly!

All other key-value pairs specified are not used by webgen. However, as layouter plugins have access
to the whole configuration section they may use their own configuration keys.


h3(#file-format-image-sec). The image section


The second section is the image data section in which additional data can be set for images. It has
the image file paths as keys. These paths have to be relative to the gallery file! The following
keys are used and/or set by the gallery handler:

* *title*: The title of the image. If not set, a default value will be assigned.
* *template*: The template file for the image page. If not set, the value of the parameter {param:
   File/GalleryHandler:imagePageTemplate} will be used.
* *orderInfo*: The images are sorted according to this key. If this key is not set, the title is
   used; if this is also not set, the image file name is used for sorting.
* *thumbnail*: If this key is set for an image, the value is assumed to be the path to a thumbnail
   for this image. Otherwise, it is set by the gallery handler and a thumbnail is created
   automatically (if the {plugin: File/ThumbnailWriter} could be loaded).
* *thumbnailSize*: The size of the automatically created thumbnail in the format "WIDTHxHEIGHT"
   where WIDTH and HEIGHT are numeric values specifying the width and the height. If not set, the
   value from the configuration section is used. If that is also not set, a default value is used
   (see {param: File/ThumbnailWriter:thumbnailSize}).
* *thumbnailResizeMethod*: The method used to create the automatic thumbnail. For more information
   about the possible values have a look at {param: File/ThumbnailWriter:resizeMethod}. If
   not set, the value from the configuration section is used, If that is also not set, a default
   value is used (see {param: File/ThumbnailWriter:resizeMethod}).
* *exif*: If not set and the exif reading library is installed, it is assigned the exif information
   of the image. The exif reading library can be installed using <code>gem install exifr</code>


h2(#thumbnail-creation). Automatic thumbnail creation


The gallery handler is able to automatically create thumbnails for the images in the image gallery
if the {plugin: File/ThumbnailWriter} is available. If so, the @thumbnailSize@ and
@thumbnailResizeMethod@ keys described above are used to create the thumbnail.

If the plugin is not available, you either have to explicitly specify a thumbnail via the
@thumbnail@ key for an image or the @width@ and @height@ attributes of the HTML @img@ tag are used
to scale the full image to the thumbnail size.


h2(#file-format-example). Example gallery file


The following example gallery file shows the most common used configuration options:

<pre>
title: Example Gallery
imagesPerPage: 32
images: example/**/*.jpg

mainPageMetaInfo:
    inMenu: false
    otherKey: value

galleryPagesMetaInfo:
    orderInfo: 10
    inMenu: true
\---
example/dir1/img1.jpg:
    title: Test title
    description: Long description of image

example/img2.jpg
    title: Title2 of pic
    mykey: mydata
</pre>

First the title of the gallery is set and the {param: File/GalleryHandler:imagesPerPage} parameter
value is overridden. Then it is specified that all files with the extension @jpg@ under the
directory @example@ should be used for this image gallery.

The next two keys set the meta information for the main page and the gallery pages. Be aware that
the @orderInfo@ meta information is set for the gallery pages. This implies that the gallery handler
automatically increments the @orderInfo@ value for each gallery page sothat they are sorted and
displayed in the menu correctly.

The second section sets the meta information for the images of the gallery. All meta information set
for the images will be available to the image template.