The Gallery module is an easy to use photo gallery which automatically shows the images of a specified directory. Subdirectories will be shown as subgalleries. It has lots of features, such as automatic thumbnailing, the use of multiple Lightbox-like templates or any css/javascript template you like, and you can give titles and descriptions to your galleries as well as your photos.

How Do I Use It

First, insert the module with the {Gallery} tag into your page or template anywhere you whish. Then upload some images with the Image Manager, File Manager (e.g. multiple images in zipfile) or FTP to the uploads/images/Gallery/ directory. You can also add multiple images with the built-in upload function (see below).

That's it!

If you want more photo galleries, simply create a subdirectory and upload your photos as described. By adding parameters to the {Gallery} tag, you can easily manipulate which subgallery will be shown in which template, e.g. {Gallery dir="holidays/Netherlands2009" template="Colorbox"}

By default the thumbnails from the Image Manager are used to display the photo galleries.

Advanced Options, but still easy to use

In the admin section you have lots of other options:

Set a photo as the default for a gallery, so it will show in the parent gallery as a 'album-cover' in stead of the default folder-icon.
Give titles and descriptions to galleries.
Set a default template for each gallery.
Set thumbnail sizes for each template, with posibilities to scale, crop and/or zoom the images.
Specify for each template in which order the photos have to be sorted.
Overrule the sorting manually by dragging&dropping the photos in the galleries list. (Note the change of the mousepointer)
Give titles and descriptions to photos.
Switch a specific photo or gallery to inactive, preventing it from display.
Edit/copy templates or create new ones. Check the info-icon beneath the template-code for the available variables.

All titles, descriptions and settings are stored in the database. The database will synchronize with the filedirectory each time the according gallery is visited in the Gallery-admin.

A little warning: when you move an image or subdirectory to another directory with FileManager, ImageManager or FTP, you will lose its title, description and settings! Always use the built-in move-function of Gallery.

Easily insert Gallery tags with TinyMCE

Gallery comes with a plugin for TinyMCE, which makes it more easy to include specific subgalleries to a page content.

To activate the plugin you go to the TinyMCE admin page, tab Plugins. Check the "gallery_picker" and save the settings. Then go to the tab Profiles and add "gallery_picker" to a toolbar of both backend profiles.

A Gallery icon will appear in the TinyMCE toolbar. Click on it and it will show a list with the available subgalleries you can choose. It will insert the Gallery tag with the according dir parameter.

Upload and resize images

The Gallery module has its own upload function. It uses the SWFUpload JavaScript/Flash library to upload multiple files at once by ctrl/shift-selecting in dialog. For this to work, your browser needs to have a recent Flash Player plugin.

To prevent users from uploading big size images, you can set maximum upload sizes in the options tab. Bigger images will be resized client side before upload. Proportions of the original image are maintained.

Custom Fields

The Gallery module allows defining numerous custom fields. A custom field can belong to a subgallery or to an image.

Gallery-related fields can be called directly in the gallerytemplate with {$fields.your_field_alias.name} and {$fields.your_field_alias.value}. You could also create a foreach loop on {$fields}.

<ul>
{foreach from=$fields item=field}
<li>fieldname '{$field.name}' has value: '{$field.value}'</li>
{/foreach}
</ul>

Image- and subgallery-related fields can be called within the images foreach loop in the gallerytemplate with {$image->fields.your_field_alias.name} and {$image->fields.your_field_alias.value}

<ul>
{foreach from=$image->fields item=imagefield}
<li>fieldname '{$imagefield.name}' has value: '{$imagefield.value}'</li>
{/foreach}
</ul>

Edit, Import and Export Gallery templates

In order to edit templates, the user must belong to a group with the 'Modify Templates' permission.

Gallery templates can be separately downloaded from the Gallery module Forge. The import session will overwrite if the checkbox is on and the name of the template already exists. Note that an update of the Gallery module will not affect your module templates.

If you want to create your own template and be able to export it, be shure to put any needed files (besides the default available ones) in its own folder with the template name in modules/Gallery/templates/. Those files will be included in the xml exportfile automatically. Click on the about link to edit the version number and the about text.

Templates can be set as invisible in template dropdown, so they can't be chosen by normal admin-users, only by users with 'Modify Templates' permission.

Documentation for available Gallery templates

AE-Gallery (= AD-Gallery) http://coffeescripter.com/code/ad-gallery
Colorbox http://colorpowered.com/colorbox/
Cycle http://jquery.malsup.com/cycle/lite/
Fancybox http://www.fancybox.net/
Lightbox http://lokeshdhakar.com/projects/lightbox2/
Lytebox http://lytebox.com/
PrettyPhoto http://www.no-margin-for-errors.com/projects/prettyphoto-jquery-lightbox-clone/
Slimbox http://www.digitalia.be/software/slimbox/
Thickbox http://www.codylindley.com/ / http://jamazon.co.uk/web/2008/03/17/thickbox-31-ie7-positioning-bug/

Gallery template variables

These are the variables you can use to customize your template:

{$module_message} - error message, is only set if there's a message
{$gallerytitle} - title of the gallery. If there is no title, this will show the directory name
{$gallerycomment} - comment of the gallery
{$galleryid} - unique id for the gallery
{$parentlink} - link to the parent folder
{$parent_url} - url to the parent folder
{$parent_txt} - text to create a link with above url
{$hideparentlink} - true/false
{$imagecount} - shows e.g. "6 images", depending on language
{$itemcount} - number of items, images + folders
{$numimages} - number of images
{$numdirs} - number of folders
{$pages} - number of pages
{$currentpage} - the current pagenumber
{$prevpage} - link to previous page, if applicable
{$prevpage_url} - url to previous page, if applicable
{$prevpage_txt} - text to create a link with above url
{$nextpage} - link to next page, if applicable
{$nextpage_url} - url to next page, if applicable
{$nextpage_txt} - text to create a link with above url
{$pagelinks} - links to each existing page
{$fields.your_field_alias.name} - gallery custum field name
{$fields.your_field_alias.value} - gallery custom field value
{$fields.your_field_alias.type} - gallery custom field type
{$images} - array with keys:
- file - relative path to the original image (or subgallery)
- filename - filename of the image (or subgallery)
- title - title of the image
- titlename - this shows the title if there is one, or else the filename
- comment - comment to the image
- active - true/false
- filedate - creation date/time
- thumb - relative path to the thumbnail. In case of a subgallery, this wil revert to the image which is set as default in that subgallery. If no image is set as default, a standard folder-icon will be used.
- fileid - unique id for the image or subgallery
- isdir - true if it's a subgallery
- galleryid - id of the gallery the image belongs to
- gallery_url - url to gallery the image belongs to
- fields.your_field_alias.name - custum field name
- fields.your_field_alias.value - custom field value
- fields.your_field_alias.type - custom field type

Global Gallery Options

To edit the global Gallery options, the user must belong to a group with the 'Modify Site Preferences' permission.

Permissions

Backend users need the permission "Use Gallery" to be able to choose the module in the admin menu.

Then, with the option "Require userpermissions to edit subgalleries" turned off (=default), the user can edit/add all (sub)galleries.

When the option "Require userpermissions to edit subgalleries" is turned on, a multi-select field "editors" becomes visible in every (sub)gallery. The user can only edit the (sub)galleries he/she (or his/her group) is assigned to by the 'editors' field, otherwise the (sub)galleries are only readable.

Users with the permission "Gallery - Add subgalleries" are able to create new subgalleries, but only in subgalleries they already have permission to edit.

Users with the permission "Gallery - Edit all galleries" can always edit all subgalleries, wether they are assigned as editor or not.

Users with the permission "Modify Templates" can define custom fields, create new templates or edit/copy existing ones.

Users with the permission "Modify Site Preferences" are able to set Gallery options in the options tab.

Parameters

(optional) dir="sub1/sub2" - Parameter to specify a directory, relative to uploads/images/Gallery/

(optional) template="" - Use a separate database template for displaying the photo gallery. This template must exist and be visible in the template tab of the Gallery admin, though it does not need to be the default. If this parameter is not specified, then the template which is assigned to the directory will be used, else the default template.

(optional) targetpage="" - Page to display Gallery in. This can either be a page alias or an id. Used to allow Gallery to be displayed in a different page template.

(optional) number="100" - Maximum number of imagethumbs to display (per page). Leaving empty will show all images.

(optional) start="1" - Start at the nth image. Leaving empty will start at the first image.

(optional) show="all" - Overide which images have to be shown. Possible values are:

'active' - to display the images marked as active (default)
'inactive' - to display only the images marked as inactive
'all' - to display all images

(optional) action="default" - Override the default action. Use it in combination with the above parameters. Possible values are:

'showrandom' - to display a set of random thumb-images (applies only to the images which are stored in the database, defaults to a number of 6 images). Use '/*' after the directoryname in the dir parameter to include images from subdirectories
'showlatest' - to display the most recently added images (applies only to the images which are stored in the database, defaults to a number of 6 images) The dir parameter can be set, or the default Gallery-root will be used. Subdirectories are automatically included
'showlatestdir' - to display a set of random thumb-images from the most recently added directory (applies only to the images which are stored in the database, defaults to a number of 6 images)
'gallerytree' - to display links to all galleries and subgalleries. This uses the gallerytree template by default, but this can be changed with the template parameter. Use the dir parameter to display a subset of the gallerytree. (applies only to the galleries which are stored in the database)

Note that images are only stored in the database when the specific gallery is visited in the admin or frontend.

(optional) img="10" - Call a single image with {Gallery img=123}. The html output can be modified in the templates tab. The thumb-size and JavaScript system can be set by choosing a template with the dropdown field.

Troubleshooting

Images do not show in frontend

Error: Images are not displayed in the frontend, yet they do appear in the backend of Gallery and in ImageManager.

Solution:

1) If you use the mod_rewrite method for pretty urls, make sure you have the {metadata} tag in the <head> section of your page template. It provides you the necessary <base href="..."> tag in your html code. Also check http://docs.cmsmadesimple.org/configuration/pretty-url

2) Modify the gallery template you use. Change {$image->file} to {$image->file|escape:'url'|replace:'%2F':'/'} only where it represents a link to an image! (not to a dir). Do this for the thumbs also: change {$image->thumb} to {$image->thumb|escape:'url'|replace:'%2F':'/'}. Note that in most templates you must change the $image->thumb variable two times and the $image->file variable just once (in case of Fancybox that is the second one).

The fancybox/thickbox/colorbox system does not work

Error: Large images open in a new white page, not in an overlay on the current page.

Solution: Check your html sourcecode if there are more calls to the jQuery script. jQuery should only be called once! If you use jQuery in your pagetemplate, you can simply delete the jQuery call from the Gallery-template (probably the first line in the javascript field).

The frontend goes blank

Error: The frontend shows a blank page or raw text without css-layout. If you turn debug on in config.php, you see the error message:

Catchable fatal error: Object of class stdClass could not be converted to string in 
/_your_root_dir_/tmp/templates_c/Printing^%%CC^CC3^CC3377B7%%module_db_tpl%3APrinting%3Blinktemplate.php
on line 22

Solution: Besides Gallery also the Printing module seems to use the {$image} variable, specifically in the Link template. You can delete the last {$image} tag in the Link template of the Printing module (just the one right before {$linktext}, as it shouldn't have been there at all).

The backend goes blank

Error: The backend shows a blank page or raw text without css-layout.

Solution: See if you have uploaded an image to uploads/images/Gallery/ (or one of its subdirectories) bigger then 2 megapixel. If that is the case, your server probably ran out of recources while Gallery was trying to create a thumbnail out of the big image. You might want to delete it.

SWF-upload Error #2032

Error: mod_security: Access denied with code 403. Error processing request body: Multipart: final boundary missing [severity "EMERGENCY"] [hostname "www.cmsmadesimple.org"] [uri "/modules/Gallery/function.upload.php"]

Solution:

1) Add "SecFilterEngine Off" to the .htaccess file in the root of the website, or add it to a new .htaccess file in the modules/Gallery/ folder

2) Make sure there isn't a slash at the end of your url in this line of the config.php file: $config['root_url'] = 'http://www.yourwebsite.com';

3) CHMOD the 'modules' directory to 755 (See this forumtopic)

Black area when hovering in the enlarged photo

Error: When hovering over the enlarged photo a large black area is shown on top of the photo.

Solution: Delete (or quote out /* */) the line "background: inherit;" in the layout stylesheet in the "default link styles" section. (a, a:hover, a:active, a:visited)

Other Errors

Error: My problem was not described here.

Solution: Set Debug to 'true' in config.php and see if any error messages appear. Look also for error messages in the html sourcecode. Maybe the error message tells you enough to solve the issue yourself. Someone else may have encountered the same problem before you, so you could also search the CMSms forum for possible solutions. If you haven't found any related topics, please feel free to open a new forumtopic.

back to Modules

This page in: English - Deutsch - Español - Français - Italiano - Lietuvių - Nederlands - Norsk - Polski - Česky - Русский - Svenska - Tiếng Việt - عربي - 日本語简体中文

User Handbook/Admin Panel/Content/Gallery

User Handbook/Admin Panel/Content/Gallery

Gallery

Contents

The Gallery Project Page

Frequently Asked Questions

Module Help

What Does This Do?

How Do I Use It

Advanced Options, but still easy to use

Easily insert Gallery tags with TinyMCE

Upload and resize images

Custom Fields

Edit, Import and Export Gallery templates

Documentation for available Gallery templates

Gallery template variables

Global Gallery Options

Permissions

Parameters

Troubleshooting

Images do not show in frontend

The fancybox/thickbox/colorbox system does not work

The frontend goes blank

The backend goes blank

SWF-upload Error #2032

Black area when hovering in the enlarged photo

Other Errors

User Handbook/Admin Panel/Content/Gallery

From CMSMS