Gallery (I18N enabled) - GetSimpleCMS-CE-plugins/plugin-i18n-Gallery GitHub Wiki

This plugin allows you to define multiple image galleries and display them in various ways:

• supports multiple galleries (like GSgallery)
• supports selection of images from data/uploads and any sub directories
• supports sorting of images (like the pages in I18N Navigation navigation structure)
• supports the I18N plugin, i.e. multiple languages
• supports a title, a description and tags per image
• supports filtering of a gallery by one or multiple tags
• displays galleries in multiple ways (e.g. fancybox, prettyPhoto, s3Slider)
• some galleries (e.g. fancybox, prettyPhoto) degenerate nicely with Javascript turned off
• displays thumbnails similarly to http://www.rcosstickphoto.com/ (but can be overridden with CSS)
• allows to set any thumbnail and image sizes (per gallery)
• automatically scales images according to these sizes
• can automatically start slide shows
• can display a specific image of a gallery
• supports a gallery preview (like view for Edit Page)
• all files reside in standard folders (images in data/uploads, thumbnails in data/thumbs, ...)
• supports full undo after saving, deleting, renaming galleries
• no Flash, no database required

cycle is a slideshow plugin that supports many different types of transition effects.

Optional parameters:

• type: must be cycle
• width: maximum width of images in pixels (integer)
• height: maximum height of images in pixels (integer)
• textpos: position of text - left, right, top, bottom, overlay or "" (no text)
• textwidth: width or height of text depending on textpos, in pixels (integer)
• interval: interval between images in milliseconds (integer)
• effect: scrollLeft, scrollRight, scrollUp, scrollDown, fade, growX, growY, turnLeft, turnRight, turnUp, turnDown, uncover, wipe or none
• navtype: type of navigation - dots, numbers or images (3D dots)

cycle is a slideshow plugin that supports many different types of transition effects.

FancyBox is a tool for displaying images and can display a title along with the image. It does not have a slideshow feature.

Optional parameters:

• type: must be fancybox
• thumbwidth: maximum width of thumbnails in pixels (integer)
• thumbheight: maximum height of thumbnails in pixels (integer)
• width: maximum width of images in pixels (integer)
• height: maximum height of images in pixels (integer)

prettyPhoto is a jQuery lightbox clone. It features a slideshow mode and can display both titel and description of an image.

Optional parameters:

• type: must be prettyphoto
• thumbwidth: maximum width of thumbnails in pixels (integer)
• thumbheight: maximum height of thumbnails in pixels (integer)
• width: maximum width of images in pixels (integer)
• height: maximum height of images in pixels (integer)
• autostart: 1 = yes, 0 = no
• interval: interval between images in milliseconds (integer)
• theme: pp_default, light_rounded, dark_rounded, light_square, dark_square or facebook

s3Slider displays slideshows, consisting of images along with titles and descriptions directly on the page. All images must have the same size.

Optional parameters:

• type: must be s3slider
• width: maximum width of images in pixels (integer)
• height: maximum height of images in pixels (integer)
• textpos: position of text - left, right, top or bottom
• interval: interval between images in milliseconds (integer)

Download I18N Gallery and unzip it into your plugins directory.

Enable sitewide cookies in your gsconfig.php and make sure, your website base URL in the Settings matches the URL that you use to login.

If you encounter problems, check

• if the file plugins/i18n_gallery/loadtab.php was copied to admin
• if a directory data/i18n_gallery exists and is read- and writeable
• if a directory backups/i18n_gallery exists and is read- and writeable
• if the file plugins/i18n_gallery/gallery.xml was copied to data/pages (gallery.xml is not used for 2.1+)
• if your template calls get_header()
• if there is a jQuery.noConflict(); in your javascript code - remove it!

and correct it.

If your template includes jQuery, it must be at least version 1.4, it must be included before the get_header() call and you should have switched on "Do not include jQuery" in the Gallery Settings. Usage

Go to the Galleries tab in your GetSimple administration and create a new gallery, add images and give it a title, a name and a type.

Add the following in your page (replace my-gallery-name with the name of the gallery):

(% gallery name=my-gallery-name %)

To add a gallery to your template, use

<?php get_i18n_gallery_header('my-gallery-name'); ?>

in your HTML header and

<?php get_i18n_gallery('my-gallery-name'); ?>

in the HTML body (e.g. the sidebar).

Add a link consisting of an image of a gallery by adding the following to your page (the url normally is the page which contains the gallery, but it can be any page):

(% gallerylink name=my-gallery-name url=my-gallery-slug thumb=0 %)

(omit thumb to output the title instead of a thumbnail or use thumb=random for a random thumbnail)

To add a link in your template, use

<?php get_i18n_gallery_link('my-gallery-name',
          array('url'=>'my-gallery-slug', 'thumb'=>0)); ?>

You can customize the gallery call with the following parameters:

• type - the type of gallery to show: cycle, fancybox, prettyphoto, s3slider or supersized
• width - maximum width of images in pixels, larger ones will be scaled down
• height - maximum height of images in pixels, larger ones will be scaled down
• pic - show this image immediately, will stop slide show: 0, 1, 2, ...
• tags - only show the images tagged with these tags, multiple tags have to be separated by comma
• id - use it as an identifier, if you include a gallery more than once on a page

For gallery types offering slide shows:

• interval - time interval between slides in milliseconds (ms)
• autostart - if the slide show should be automatically started: true, false

For gallery types displaying thumbnails:

• thumbwidth - maximum width of the thumbnails in pixels
• thumbheight - maximum height of the thumbnails in pixels
• thumbtitles - if 0, false or 'false', don't show titles, otherwise show titles below thumbs
• thumb - show only n-th image as thumbnail (version 0.7+): 0, 1, 2, ..., random (switches off pagify since 1.7.3)
• pagify - if not 0, false or 'false', create a pagination for the thumbnails (see pagesize)
• pagesize - the number of thumbnails on one page (only if pagify is switched on)

For gallery links only name, thumb, thumbwidth, thumbheight and the following parameters are used (omitting thumb will output the title instead of a thumbnail):

• url - the slug of the page with the gallery (required)
• parent - the parent slug of the page with the gallery (optional)

All parameters except type are only used, if supported by the selected gallery type.

Example:

(% gallery name=my-gallery type=prettyphoto autostart=true %)

or (make sure to have the same parameters in both function calls):

<?php get_i18n_gallery_header('my-gallery',
          array('type'=>'prettyphoto', 'autostart'=>true)); ?>
...
<?php get_i18n_gallery('my-gallery',
          array('type'=>'prettyphoto', 'autostart'=>true)); ?>

The following URL parameters are recognized, if they are not given in the call:

• name - the name of the gallery
• type - the type of gallery to show (see above)
• imagetags - only show the images tagged with these tags (see above) (before version 1.5.1 this parameter was named tags, which clashed with I18N Search)

The following URL parameters are always recognized and override parameters in the call:

pic - show this image immediately, will stop slide show: 0, 1, 2, ... or (if you have multiple galleries on one page) galleryname:0, galleryname:1, ...

Assuming you have a page gallery with the following code (this is initially copied to your pages directory, if you do not yet have a page with this name)...

(% gallery %)

... you can call a gallery mygallery with

http://my.site/gallery?name=mygallery&type=fancybox&pic=2

You can filter galleries by tags. As an example here the gallery is shown three times with different filters (some images have multiple tags and thus appear in multiple categories).

If no tags are given in the gallery placeholder, you can also pass a parameter imagetags in the URL as shown below:

(% gallery name=ireland type=fancybox tags=animal %) (% gallery name=ireland type=fancybox tags=building %) (% gallery name=ireland type=fancybox tags=water %)

Multiple Tags

You can also use multiple tags to show all images having all these tags, e.g.

(% gallery name=ireland type=prettyphoto tags="landscape, building" %)

A link to the gallery showing all images:

(% gallerylink name=ireland url=i18ngallery-fancybox thumb=random %)

Or bigger:

(% gallerylink name=ireland url=i18ngallery-fancybox thumb=random thumbwidth=400 thumbheight=300 %)

A link to the gallery only showing animals:

(% gallerylink name=ireland url=i18ngallery-fancybox thumb=random tags=animal %)

I18N Gallery is extensible!

I18N Gallery offers the following hooks and filters, which can be used by other plugins to extend I18N Gallery:

• gallery-extras: action on the edit gallery page that is executed when the gallery options have been output.
• image-veto: filter function taking the arguments $name, $filename, $tags, where $name is the name of the gallery, $filename is the image file and $tags is an array of strings with the tags of this image. This function can be used to exclude images from being displayed by returning true.

Example code for a plugin extending I18N Gallery:

...
add_action('gallery-extras', 'myplugin_set_fancybox');
add_filter('image-veto','myplugin_image_veto');

function myplugin_set_fancybox() {
  if (!@$_GET['name']) { // creating new gallery
?>
  <script type="text/javascript">
    $(function() {
      // set default value for type
      $('[name=post-type]').val('fancybox');
    });
  </script>
<?php
  }
}

function myplugin_image_veto($gallery, $filename, $tags) {
  // veto images tagged private
  if (in_array('private', $tags)) return true;
  return false;
}
...

You can create new gallery types by adding a gallery plugin.

• create a new PHP file plugin_mytype.php in plugins/i18n_gallery, and in this file
• register the type with i18n_gallery_register('mytype', 'Name for dropdown', 'description including licensing information', 'i18n_gallery_mytype_edit', 'i18n_gallery_mytype_header', 'i18n_gallery_mytype_content'),
• create a function i18n_gallery_type_edit to display the options in the administration,
• create a function i18n_gallery_type_header to output the CSS and JS includes in the HTML header
• create a function i18n_gallery_type_content to output the gallery itself.

Here is an example for a gallery plugin file named plugin_mytype.php in the directory plugins/i18n_gallery (replace mytype with the actual name):

<?php
i18n_gallery_register('mytype', 'My Type', 
  'Description including license',
  'i18n_gallery_mytype_edit', 'i18n_gallery_mytype_header', 
  'i18n_gallery_mytype_content');

function i18n_gallery_mytype_edit($gallery) {
  // called for the input fields in the gallery configuration
  // all field IDs and names must be prefixed mytype-
  // all Javascript functions must include the type name to be unique
  ...
}

function i18n_gallery_mytype_header($gallery) {
  // called in the header of a page with a gallery
  // add CSS and Javascript files, etc.
  ...
}

function i18n_gallery_mytype_content($gallery) {
  // called to actually display the gallery
  ...
}

$gallery is an associative array with all gallery parameters. It includes all input fields as parameters (names are not prefixed mytype-).

Ad i18n_gallery_type_edit:

All fields must be named mytype-xxx.

Ad i18n_gallery_type_header:

• Use helper functions from helper.php, e.g.
  • i18n_gallery_check to check for general gallery settings
  • i18n_gallery_needs_include to check if a file needs to be included or was already included for another gallery
• Make sure to separate your CSS into general parts (for all galleries of this type) and specific parts (e.g. size settings for the current gallery.

Ad i18n_gallery_type_content:

• If the gallery shows thumbnails you should check, if only one thumbnail should be displayed (function i18n_gallery_thumb) and hide all other thumbnails in this case.
• You should also check, if a specific picture ($pic) should be displayed.
• Preferably the gallery should also work with Javascript switched off (currently cycle works without Javascript and fancybox and prettyPhoto have a fallback).
• There are a lot of helper functions in helper.php, which can and should be used in the plugin. See one of the existing plugins for an example.

Javascript, Images, CSS:

• Put all Javascript, image and CSS files in the corresponding directories under plugins/i18n_gallery, preferably in subfolders.