Location: webgen / Documentation / Plugins / File / GalleryHandler Language: en Feedback: Click here

General Information

Plugin name:	File/GalleryHandler (File/DefaultHandler)
Author:	Thomas Leitner <t_leitner@gmx.at>
Summary:	Handles images gallery files
Parameters:	galleryPageTemplate: "gallery_gallery.template" The template for gallery pages. If nil or a not existing file is specified, the default template is used. imagePageTemplate: "gallery_image.template" The template for image pages. If nil or a not existing file is specified, the default template is used. images: "images/**/*.jpg" The path pattern for specifying the image files imagesPerPage: 20 Number of images per gallery page mainPageTemplate: "gallery_main.template" The template for the main page. If nil or a not existing file is specified, the default template is used.
Handled paths:	**/*.gallery

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 examples section!

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 imagePageTemplate, galleryPageTemplate and 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!

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:

$ wegben help use gallery_style

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

$ wegben use gallery_style STYLE

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 extending webgen section!

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.

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.
• filename: The base filename used for creating the page files. If not specified it is created from the title.
• lang: The language used by the gallery. If not specified, the default language is used.
• mainPageMetaInfo: Used for setting additional meta information for the main page.
• galleryPagesMetaInfo: Used for setting additional meta information for the gallery pages.
• imagePagesMetaInfo: Used for setting additional meta information for all image pages.
• layouter: Plugin used for additional gallery tasks, has to be registered under GalleryLayouter/<layouter-name>
• 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 File/ThumbnailWriter!

Two nearly always specified parameters should also be mentioned here: imagesPerPage and 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!

If you want to create a multi-lingual gallery, you need to create two gallery files which specify the same filename key and different lang keys. It’s best to first create one gallery file, fill in all the information and then copy it and change the filename and lang keys as well as all the other language specific information like titles and descriptions.

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.

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 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 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 File/ThumbnailWriter:thumbnailSize).
• thumbnailResizeMethod: The method used to create the automatic thumbnail. For more information about the possible values have a look at 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 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 gem install exifr

Automatic thumbnail creation

The gallery handler is able to automatically create thumbnails for the images in the image gallery if the 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.

Example gallery file

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

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

First the title of the gallery is set and the 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.