Differences

This shows you the differences between two versions of the page.

Link to this comparison view

dev:changes_in_2.6 [2013/04/23 15:49]
mistic100
dev:changes_in_2.6 [2014/03/16 08:07] (current)
plg is_adviser() removed
Line 1: Line 1:
 ====== Technical changes in Piwigo 2.6 ====== ====== Technical changes in Piwigo 2.6 ======
 +
 +===== 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 1.9 =====
Line 14: Line 18:
 <code>{combine_css path="themes/default/js/plugins/jquery.jgrowl.css"}</code> <code>{combine_css path="themes/default/js/plugins/jquery.jgrowl.css"}</code>
 no changes for the javascript file 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 =====
 +
 +[[http://smarty-php.googlecode.com/svn/trunk/distribution/SMARTY_2_BC_NOTES.txt|Changes between Smarty 2 and 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 [[dev:send_emails_with_piwigo|]] 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 :
 +<code php>
 +// 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)
 +</code>
 +
 +===== 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.
 +<code>
 +{combine_script id='myscript' path='path/to/dynamic.js' template=true}
 +{combine_css id='mystyle' path='path/to/dynamic.css' template=true}
 +</code>
 +
 +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
 +<code>FileCombiner::clear_combined_files();</code>
 +  * 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.
 +<code>{combine_css id='mystyle' path='path/to/dynamic.css' template=true version=$lastmod}</code>
 +===== 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 :
 +<code>
 +  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,
 +           ...
 +           )
 +</code>
 +
 +===== 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.
 
Back to top
dev/changes_in_2.6.txt · Last modified: 2014/03/16 08:07 by plg
 
 
github twitter newsletter Donate Piwigo.org © 2002-2022 · Contact