This is an old revision of the document!

Technical changes in Piwigo 2.6

Jquery UI 1.9

Jquery ui effects filename have changed. For example change

footer|combine_script require='jquery.effects.blind'


footer|combine_script require='jquery.ui.effect-blind'

We had backward naming compatibility for 2.5 but not for 2.6.

jGrowl CSS file

the file admin/themes/default/uplodify.jgrowl.css was moved to themes/default/js/plugins/jquery.jgrowl.css

use this line to include the file in your template :

{combine_css path="themes/default/js/plugins/jquery.jgrowl.css"}

no changes for the javascript file

Add action buttons


Themes have to handle two new template vars : $PLUGIN_INDEX_BUTTONS and $PLUGIN_PICTURE_BUTTONS
Plugins creators SHOULD NOT add <li> or <div> or <span> around their buttons, it's now handled by the theme.

Default implementation is

{if !empty($PLUGIN_INDEX_BUTTONS)}{foreach from=$PLUGIN_INDEX_BUTTONS item=button}<li>{$button}</li>{/foreach}{/if}

in index.tpl and

{if isset($PLUGIN_PICTURE_BUTTONS)}{foreach from=$PLUGIN_PICTURE_BUTTONS item=button}{$button}{/foreach}{/if}

in picture.tpl

TokenInput CSS + config

TokenInput CSS was moved from admin/themes/default/style.css to themes/default/js/plugins/jquery.tokeninput.css. Needs to be explicitly imported with

{combine_css path="themes/default/js/plugins/jquery.tokeninput.css"}

allowCreation parameter was renamed into allowFreeTagging


SwitchBox are used for derivatives choices, sort options, LanguageSwitch, ThemeSwitch, etc.
Now the JS code is factorized in a function available in themes/default/js/switchbox.js
Usage :

{combine_script id='core.switchbox' load='async' require='jquery' path='themes/default/js/switchbox.js'}
{footer_script require='core.switchbox'}(SwitchBox=window.SwitchBox||[]).push("#sortOrderLink", "#sortOrderBox");{/footer_script}

The CSS is still provided by themes.

Smarty 3

In template/menubar_categories.tpl, replace:




Added a function translate_dec, replace:

{$pwg->l10n_dec('singular string', 'plural string', $value)}


{$value|translate_dec:'singular string':'plural string'}

Generic template for custom pages

Many plugins add a new public page to Piwigo. Lacking of a documented way to do it, everybody was using his own method, causing display issues with some themes.

In Piwigo 2.6 we introduced a simple way to do it.

For plugins developpers

First define in loc_end_section_init trigger :

$page['body_id'] = 'whatever_you_want';
$page['is_external'] = true;

Then when you want to display the content of your page :

$template->set_filename('your_page', realpath(path to your template));
$template->assign_var_from_handle('CONTENT', 'your_page');

Check Skeleton plugin for complete example

For themes developpers

There a little modification of index.tpl : you need to add

{if !empty($CONTENT)}{$CONTENT}{/if}

in the main block of the page.

Unified Batch Manager URL

admin.php?page=batch_manager could be accessed with four URL parameters :

This has been replaced by a single parameter filter :

Now any prefilter (build-in or added by a plugin) can be accessed via this URL parameter. Build-in prefilters are : caddie, favorites, last_import, no_album, no_tag, duplicates, all_photos, no_virtual_album.

Filters can also be combined (comma separated) : &filter=prefilter-no_tag,album-##

l10n / translate + sprintf

l10n function and translate modifier have been improved : you can provide additional arguments to perform a sprintf on the translated string.

Usage is the same as PHP sprintf, it will trigger an Warning if number of arguments and replacers mismatch.

// old way
sprintf(l10n('%d comments'), $nb);
// new way
l10n('%d comments', $nb);
// old way
{'%d comments'|translate|sprintf:$nb}
// new way
{'%d comments'|translate:$nb}

(not limited to one argument)

New options for API methods

We introduced a high-level type check in the API class. When declaring your custom methods you can now specify the expected type of each parameter by filling the 'type' option.

Possible values are :

For ints and floats you can also use :

And there is the special WS_TYPE_ID for positive and not null integers.

Another new parameters option is 'info' witch allows to display additional information on the API explorer (tools/ws.htm).

Finally there are three new options (all optional) when declaring an API method:
hidden: hide the method from the reflection method (thus the API explorer)
admin_only: method only available for administrators
post_only: method only available through POST request.

Here is an example of method using all these possibilities:

        'param1' =>   array('default'=>null,
                            'info'=>'Here goes info about <b>param1</b>'),
        'param2' =>   array('type'=>WS_TYPE_ID),
        'param3' =>   array('default'=>2.5,
      'My method is awesome.',
      null, // this parameter is for runtime 'include'
        'hidden' => true,
        'admin_only' => true,
        'post_only' => true,

Note that parameters without a 'default' value or without the WS_PARAM_OPTIONAL flag are mandatory. If a parameter is mandatory and provided empty, it is considered are lacking and the server will return an error.

New API methods

Some new methods from admin_ws_api plugin.

  • pwg.groups.add
  • pwg.groups.addUser
  • pwg.groups.delete
  • pwg.groups.deleteUser
  • pwg.groups.getList
  • pwg.groups.setInfo
  • pwg.users.add
  • pwg.users.delete
  • pwg.users.getList
  • pwg.users.setInfo
  • pwg.permissions.add
  • pwg.permissions.getList
  • pwg.permissions.remove


register_user() function has been modified : the returned value is now the new user id and not the array of errors. In order to get the errors you have to provide the fifth parameter witch will be filled. New parameter $notify_user (boolean) to send the user his connection settings.

// prior 2.6
$errors = register_user($username, $password, $email, true);
// after 2.6
$user_id = register_user($username, $password, $email, true, $errors, $notify_user);

New email system

In Piwigo 2.6 we entirely rewrote email system, with the help of PHPMailer library, as well as the email template.


Third-party templates and themes can no longer modify the email template. We made this choice to avoid display issues (unlike “traditional” web, mail readers still use old HTML technics).

Piwigo 2.6 comes with one template and two color schemes : clear and dark.


The main mailing function has been considerably enhanced, particularly with the support of content template files. See send_emails_with_piwigo for more details.

Basic usage is unchanged.


This new method has the same parameters as pwg_mail() except the first one which is not present.
Unlike pwg_mail_notification_admins() it allows to send complex emails to admins.


The usage of this method completely changed. It has the same parameters as pwg_mail() except the first one witch is the group identifier. (See admin/album_notification.php file for basic usage).

Changes in $conf

Deleted parameters:

  • $conf['mail_options'] = false;
  • $conf['default_email_format'] = 'text/html';
  • $conf['alternative_email_format'] = 'text/plain';

New parameters:

  • $conf['mail_sender_email'] = ””;
  • $conf['mail_allow_html'] = true;
  • $conf['smtp_secure'] = null;

Other changes

pwg_send_mail() is deprecated.

move_ccs_rules_to_body() has been replaced by move_css_to_body() (uses Emogrifier library).

Removed triggers:

  • send_mail
  • send_mail_to
  • send_mail_subject
  • send_mail_content
  • send_mail_headers
  • mail_group_assign_vars

New triggers:

  • before_send_mail
  • before_parse_mail_template


We removed replace_space() function.
As a consequence some other functions changed :

// old
get_cat_display_name($cat_informations, $url = '', $replace_space = false)
get_cat_display_name_from_id($cat_informations, $url = '', $replace_space = false)
get_cat_display_name_cache($uppercats, $url = '', $replace_space = false, $single_link = false, $link_class = null)
// new
get_cat_display_name($cat_informations, $url = '')
get_cat_display_name_from_id($cat_informations, $url = '')
get_cat_display_name_cache($uppercats, $url = '', $single_link = false, $link_class = null)
Back to top
dev/changes_in_2.6.1384100621.txt.gz · Last modified: 2013/11/10 16:23 by mistic100
github twitter newsletter Donate © 2002-2023 · Contact