1

Technical changes in Piwigo 2.6

Pierrick Le Gall edited this page 2023-05-01 19:22:10 +02:00

Table of Contents

• Jquery 1.9
• Jquery UI 1.9
• jGrowl CSS file
• Add action buttons
• TokenInput CSS + config
• SwitchBox
• Smarty 3
• Generic template for custom pages
• For plugins developpers
• For themes developpers
• Unified Batch Manager URL
• l10n / translate + sprintf
• New options for API methods
• New API methods
• register_user()
• New email system
• Template
• pwg_mail()
• pwg_mail_admins()
• pwg_mail_group()
• Changes in $conf
• Other changes
• get_cat_display_name()
• Triggers functions
• GPS metadata
• CSS & JS as Smarty templates
• Usage
• Limitation
• query2array
• is_adviser() removed

Jquery 1.9

Upgrade to jQuery version 1.9 breaks some jQuery functions. See http://jquery.com/upgrade-guide/1.9/ : check you don't use .live() or jQuery.browser()

Jquery UI 1.9

Jquery ui effects filename have changed. For example change

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

to

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

Following http://piwigo.org/doc/doku.php?id=dev:changes_in_2.5#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

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

Changes between Smarty 2 and Smarty 3

In template/menubar_categories.tpl, replace:

{'</ul></li>'|@str_repeat:$ref_level-$cat.LEVEL}

by

{'</ul></li>'|str_repeat:($ref_level-$cat.LEVEL)}

Added a function translate_dec, replace:

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

by

{$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 http://piwigo.org/svn/extensions/skeleton/trunk/include/public_events.inc.php

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 :
&cat=caddie
&cat=recent
&cat=###
&tag=###

This has been replaced by a single parameter filter :
&filter=prefilter-caddie
&filter=prefilter-last_import
&filter=album-##
&filter=tag-##

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 :
WS_TYPE_BOOL
WS_TYPE_INT
WS_TYPE_FLOAT
For ints and floats you can also use :
WS_TYPE_POSITIVE
WS_TYPE_NOTNULL
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:

  $service->addMethod(
      'pwg.myMethod',
      'ws_my_method',
      array(
        'param1' =>   array('default'=>null,
                            'flags'=>WS_PARAM_FORCE_ARRAY,
                            'info'=>'Here goes info about <b>param1</b>'),
        'param2' =>   array('type'=>WS_TYPE_ID),
        'param3' =>   array('default'=>2.5,
                            'type'=>WS_TYPE_FLOAT|WS_TYPE_POSITIVE),
        ),
      'My method is awesome.',
      null, // this parameter is for runtime 'include'
      array(
        '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()

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.

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.

pwg_mail()

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

Basic usage is unchanged.

pwg_mail_admins()

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.

pwg_mail_group()

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

get_cat_display_name()

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)

Triggers functions

Piwigo has two type of triggers: one to notify of an event and one to allow modification of a particular variable. The triggers functions was named trigger_event() and trigger_action() witch is not a natural naming...

In 2.6 we added trigger_change() (alias of trigger_event) and trigger_notify() (alias of trigger_action).

In 2.7 the old functions will be removed.

GPS metadata

Piwigo 2.6 adds two fields in piwigo_images table : latitude and longitude. These fields are automatically filled with EXIF metadata if available and if $conf['use_exif'] is true.

They are not currently used in the core but they are available for read an write by any plugin.

When updating from 2.5, a migration task tries to get values from lat and lon fields used by Map & Earth and Open Street Maps plugins (the task also drops these two old fields).

CSS & JS as Smarty templates

Starting from Piwigo 2.6 you can add Smarty (templating) code in your CSS and JS files included with combine_css and combine_script.

Usage

Add template=true in the file declaration.

{combine_script id='myscript' path='path/to/dynamic.js' template=true}
{combine_css id='mystyle' path='path/to/dynamic.css' template=true}

The template engine will first parse the file as a common template file then send it to the file combiner which merges all CSS and JS files in two single files.

Limitation

The CSS and JS template files are only parsed when the file combiner needs to regenerate the combined files. This means you can not use real dynamic values in those files.
This feature must only be used for CSS and JS files depending on a configuration param, chaging very rarely.
When the said configuration changes you must notify the template engine. There are two ways to do that:

• clear all combined files by calling

FileCombiner::clear_combined_files();

• use the version parameter of combine_css and combine_script. For example, EasyCaptcha plugin saves the timestamp of last change in his configuration and uses it as CSS version.

{combine_css id='mystyle' path='path/to/dynamic.css' template=true version=$lastmod}

query2array

Piwigo 2.6 introducs a new helper. query2array builds an array from a SQL query, it actually combines the possibilities of hash_from_query, simple_hash_from_query, array_from_query.

The purpose it to provide a single comprehensive function for data retrieval.

It takes three parameters : SQL query, key name (optional), value name (optional).

Here are the possible return values :

  Depending on $key_name and $value_name it can return :
 
     - an array of arrays of all fields (key=null, value=null)
         array(
           array('id'=>1, 'name'=>'DSC8956', ...),
           array('id'=>2, 'name'=>'DSC8957', ...),
           ...
           )
 
     - an array of a single field (key=null, value='...')
         array('DSC8956', 'DSC8957', ...)
 
     - an associative array of array of all fields (key='...', value=null)
         array(
           'DSC8956' => array('id'=>1, 'name'=>'DSC8956', ...),
           'DSC8957' => array('id'=>2, 'name'=>'DSC8957', ...),
           ...
           )
 
     - an associative array of a single field (key='...', value='...')
         array(
           'DSC8956' => 1,
           'DSC8957' => 2,
           ...
           )

is_adviser() removed

Function is_adviser() has been deprecated for several releases. Now it has been removed. If you keep it your code, Piwigo will crash.