Extend I18N Gallery

I18N Gallery is extensible!

Hooks

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;
}
...

New Gallery Types

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.

Post the new gallery plugin in the support thread or send it to me by private mail.