Technical changes in Piwigo 2.7

About Plugins / PHP

trigger_change / trigger_notify

Following what was announced for Piwigo 2.6, the functions trigger_event and trigger_action were deleted. You must use trigger_change and trigger_notify instead.

add_event_handler() 4th parameter

The fourth parameter of add_event_handler function was used to tell the number of parameters which will be transmitted to the callback. This is no longer used: all parameters given to trigger_change or trigger_notify are always transmitted to all callback.

But the fourth parameter is still used: if a string is given it will be used as a file path included just before the callback (with include_once).

// procedural
add_event_handler('init', 'my_init',
  MY_PLUGIN_PATH . 'include/callbacks.php'
// OOP with static method
add_event_handler('init', array('MyClass', 'init'),
  MY_PLUGIN_PATH . 'include/myclass.php'

If the 4th parameter is anything else than a string it is ignored.

Plugin maintenance class

We introduced a new pattern for maintenance of plugins, this uses a PHP class named after your plugin and define in a maintain.class.php file with the following methods:

 * PLUGINID must be replaced by the directory name of your plugin
class PLUGINID_maintain extends PluginMaintain
  function install($plugin_version, &$errors=array()) { ... }
  function activate($plugin_version, &$errors=array()) { ... }
  function update($old_version, $new_version, &$errors=array()) { ... }
  function deactivate() { ... }
  function uninstall() { ... }

The update method can be called outside the automatic update process, for example if plugin files are manually replaced with a newer version, this ensure full support on hosts which block auto-update.

The old file is still supported and will never be removed.


conf_update_param function has been enhanced:

  • if an array or object is provided as a value, it will be serialized and escaped before database insertion
  • provide true as third parameter to update the $conf global as well (with unserialized value)
  • if you prefer JSON over PHP serial you can provide a custom serializer as fourth parameter
conf_update_param('my_key', $my_array, true,
  create_function('$v', 'return addslashes(json_encode($v));'));
// here, $conf['my_key'] == $my_array;

Two utility functions was added: safe_unserialize and safe_json_decode which can be used if you are not sure if the value has already been unserialized or not.


The plugins TokenInput and Chosen have been removed in favor to Selectize.

Use this to load the script:

{combine_script id='jquery.selectize' load='footer' path='themes/default/js/plugins/selectize.min.js'}

The old plugins sources will be removed in further version, your are advised to migrate now.


Selectize comes with two colorschemes, dark and clear loaded conditionally with help of $themeconf['colorscheme'].

Use this to load the CSS:

{combine_css id='jquery.selectize' path="themes/default/js/plugins/selectize.{$themeconf.colorscheme}.css"}

We added a LocalStorage cache for the lists of tags/albums/users/groups. It is used on every core Selectize box and considerably speeds-up loading time of admin pages. Here is how to use it.

Include the script (before or after Selectize):

{combine_script id='LocalStorageCache' load='footer' path='admin/themes/default/js/LocalStorageCache.js'}

Add the HTML element:

<select data-selectize="categories" data-value="{$associated_albums|@json_encode|escape:html}"
        data-default="{$STORAGE_ALBUM}" name="associate[]" multiple>

$associated_albums must be an array of identifiers for the preselect items. data-default represents a item which can't be removed.

Init the cache:

var categoriesCache = new CategoriesCache({
  serverKey: '{$CACHE_KEYS.categories}',
  serverId: '{$CACHE_KEYS._hash}',
  rootUrl: '{$ROOT_URL}'

$CACHE_KEYS array is used to sync the cache with the server, it contains state keys for categories, tags, users and groups.

Init Selectize with the cache:

Add album popin

The reusable “add new album” popin (using Colorbox) has obviously been rewritten to use (exclusively) Selectize and the cache.

As before, include the template:

{include file='include/'}

Add the receiving select and add button:

<select data-selectize="categories" data-value="{$selected_category|@json_encode|escape:html}"
  data-default="first" name="category" style="width:400px"></select>
<br>{'... or '|@translate}
<a href="#" data-add-album="category" title="{'create a new album'|translate}">
  {'create a new album'|@translate}</a>

data-add-album value refers to the name of the select.

Apply pwgAddAlbum micro-plugin by providing the cache:

jQuery('[data-add-album]').pwgAddAlbum({ cache: categoriesCache });

Batch Manager, add filters

We have added 2 trigger_change to add filters in the Batch Manager. The first on batch_manager_register_filters let you register a filter:

add_event_handler('batch_manager_register_filters', 'bmab_register_filter');
function bmab_register_filter($filters)
  if (isset($_POST['filter_added_by_use']))
    check_input_parameter('filter_added_by', $_POST, false, PATTERN_ID);
    $filters['added_by'] = $_POST['filter_added_by'];
  return $filters;

The second trigger_change batch_manager_perform_filters let you define the list of photos that match the filter, and add the set of photos to $filter_sets.

add_event_handler('batch_manager_perform_filters', 'bmab_perform_filter');
function bmab_perform_filter($filter_sets)
  if (isset($_SESSION['bulk_manager_filter']['added_by']))
    $query = '
  WHERE added_by = '.$_SESSION['bulk_manager_filter']['added_by'].'
    $filter_sets[] = array_from_query($query, 'id');
  return $filter_sets;

See a full example on

Take A Tour plugin

The plugin allow external sources like plugins to start their own tour. Check admin.tpl and the files tour.tpl and of the existing tours to get familiar with the system, but here some explanations:

  • the launch of a tour is made throught $_GET or $POST_ and require a pwg_token
  • $_REQUEST['submited_tour_path'] contains the path to the file, and is relative to root_of_piwigo/plugins/TakeATour/ (e.g. $_GET['submited_tour_path']=../MyPlugin/tour/introduction )
  • contains AT LEAST the value of $TOUR_PATH which is the path to the tpl file and which is relativ eto the root of Piwigo (e.g. $TOUR_PATH = PHPWG_PLUGINS_PATH.'MyPlugin/tours/introduction/mytour.tpl';). is loaded before the parsing of the tpl of the tour and in the init event: so it will contains direct code to assign vars to your tpl, and can also contains additionnal add_event_handler. These add_event_handler are currently used as prefilter to add css id as anchors for steps.
  • and so the tpl file should be made using the existing tours as examples: the script used is where you can found a doc

Take A Tour loads the js and css needed, you just have to provide a and a tpl file and to load the language (it's recommended using the new option force_fallback like load_language('plugin.lang', PHPWG_PLUGINS_PATH .'MyPlugin/', array('force_fallback'⇒'en_UK')); because empty text means that the step will be skiped)

The plugin allows also the customization of the content of existing tours:

  • $conf['enable_synchronization'] is taken into account, no need to worry about that
  • but anything else can be changed by simply adding custom language files (see LocalFiles Editor)
  • steps in a tour can be skipped by simply emptying the content and title of that step, in the lang file
  • tours can be hidden in the admin of Take A Tour with the array $conf['TakeATour_tour_ignored']

About Themes / tpl and CSS


With Selectize on search.tpl, we need to know if the theme is rather clear or dark, to load the appropriate CSS file (clear background or dark background). In your, add the “colorscheme”. It can be “dark” or “clear” only. This parameter will be used for other things like colorbox background or guestbook colors… (very useful for plugins)

$themeconf = array(
  'name'  => 'clear',
  'parent' => 'default',
  'colorscheme' => 'clear',

picture.tpl - disable website field

We added an option to disable or enable the website field on comment add form. You must wrap the field in a IF block:

{if $comment_add.SHOW_WEBSITE} ... {/if}

{$THUMB_SRC} template variable is not assigned anymore. Use instead {$current.derivatives.thumb→get_url()}

search.tpl - major changes

The template search.tpl has deeply modified, so if you have a custom one in your theme, you'd better restart your customization from the new themes/default/template/search.tpl

Back to top
dev/changes_in_2.7.txt · Last modified: 2014/09/22 15:25 by plg
github twitter facebook google+ newsletter Donate © 2002-2017 · Contact