dev:changes_in_2.6 [Piwigo Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Technical changes in Piwigo 2.6 ======

===== Jquery UI 1.9 =====
Jquery ui effects filename have changed. For example change
<file>footer|combine_script require='jquery.effects.blind'</file>
to
<file>footer|combine_script require='jquery.ui.effect-blind'</file>
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 :
<code>{combine_css path="themes/default/js/plugins/jquery.jgrowl.css"}</code>
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
<code>{if !empty($PLUGIN_INDEX_BUTTONS)}{foreach from=$PLUGIN_INDEX_BUTTONS item=button}<li>{$button}</li>{/foreach}{/if}</code>
in index.tpl and
<code>{if isset($PLUGIN_PICTURE_BUTTONS)}{foreach from=$PLUGIN_PICTURE_BUTTONS item=button}{$button}{/foreach}{/if}</code>
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 <code>{combine_css path="themes/default/js/plugins/jquery.tokeninput.css"}</code>
**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 :
<code>{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}</code>

The CSS is still provided by themes.

===== Smarty 3 =====

In template/menubar_categories.tpl, replace:
<code>{'</ul></li>'|@str_repeat:$ref_level-$cat.LEVEL}</code>
by
<code>{'</ul></li>'|str_repeat:($ref_level-$cat.LEVEL)}</code>

Added a function **translate_dec**, replace:
<code>{$pwg->l10n_dec('singular string', 'plural string', $value)}</code>
by
<code>{$value|translate_dec:'singular string':'plural string'}</code>

===== 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 :
<code>$page['body_id'] = 'whatever_you_want';
$page['is_external'] = true;</code>

Then when you want to display the content of your page :
<code>
$template->set_filename('your_page', realpath(path to your template));
$template->assign_var_from_handle('CONTENT', 'your_page');</code>

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
<code>{if !empty($CONTENT)}{$CONTENT}{/if}</code>
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.

<code=php>
// 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}
</code>
(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:
<code php>
  $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,
        )
    );
</code>

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 [[http://piwigo.org/ext/extension_view.php?eid=713|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.

<code php>
// prior 2.6
$errors = register_user($username, $password, $email, true);

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


===== 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 [ PLACEHOLDER this page ] 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['mail_theme'] = 'clear'; -- will be moved to GUI
  * $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
Back to top
dev/changes_in_2.6.1383760693.txt.gz · Last modified: 2013/11/06 17:58 by mistic100
Sitemap Recent changes
Show page
Old revisions