upgrading.rst 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559
  1. Upgrading Plugins
  2. #################
  3. Prepare your plugin for the next version of Elgg.
  4. See the administator guides for :doc:`how to upgrade a live site </admin/upgrading>`.
  5. .. contents:: Contents
  6. :local:
  7. :depth: 2
  8. From 1.10 to 1.11
  9. =================
  10. Comment highlighting
  11. --------------------
  12. If your theme is using the file ``views/default/css/elements/components.php``, you must add the following style definitions in it to enable highlighting for comments and discussion replies:
  13. .. code:: css
  14. .elgg-comments .elgg-state-highlight {
  15. -webkit-animation: comment-highlight 5s;
  16. animation: comment-highlight 5s;
  17. }
  18. @-webkit-keyframes comment-highlight {
  19. from {background: #dff2ff;}
  20. to {background: white;}
  21. }
  22. @keyframes comment-highlight {
  23. from {background: #dff2ff;}
  24. to {background: white;}
  25. }
  26. From 1.9 to 1.10
  27. ================
  28. File uploads
  29. ------------
  30. If your plugin is using a snippet copied from the ``file/upload`` action to fix detected mime types for Microsoft zipped formats, it can now be safely removed.
  31. If your upload action performs other manipulations on detected mime and simple types, it is recommended to make use of available plugin hooks:
  32. - ``'mime_type','file'`` for filtering detected mime types
  33. - ``'simple_type','file'`` for filtering parsed simple types
  34. From 1.8 to 1.9
  35. ===============
  36. In the examples we are upgrading an imaginary "Photos" plugin.
  37. Only the key changes are included. For example some of the deprecated functions are not mentioned here separately.
  38. Each section will include information whether the change is backwards compatible with Elgg 1.8.
  39. The manifest file
  40. -----------------
  41. No changes are needed if your plugin is compatible with 1.8.
  42. It's however recommended to add the ``<id>`` tag. It's value should be the name of the directory where the plugin is located inside the ``mod/`` directory.
  43. If you make changes that break BC, you must update the plugin version and the required Elgg release.
  44. Example of (shortened) old version:
  45. .. code:: xml
  46. <?xml version="1.0" encoding="UTF-8"?>
  47. <plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
  48. <name>Photos</name>
  49. <author>John Doe</author>
  50. <version>1.0</version>
  51. <description>Adds possibility to upload photos and arrange them into albums.</description>
  52. <requires>
  53. <type>elgg_release</type>
  54. <version>1.8</version>
  55. </requires>
  56. </plugin_manifest>
  57. Example of (shortened) new version:
  58. .. code:: xml
  59. <?xml version="1.0" encoding="UTF-8"?>
  60. <plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
  61. <name>Photos</name>
  62. <id>photos</id>
  63. <author>John Doe</author>
  64. <version>2.0</version>
  65. <description>Adds possibility to upload photos and arrange them into albums.</description>
  66. <requires>
  67. <type>elgg_release</type>
  68. <version>1.9</version>
  69. </requires>
  70. </plugin_manifest>
  71. $CONFIG and $vars['config']
  72. ---------------------------
  73. Both the global ``$CONFIG`` variable and the ``$vars['config']`` parameter have been deprecated. They should be replaced with the ``elgg_get_config()`` function.
  74. Example of old code:
  75. .. code:: php
  76. // Using the global $CONFIG variable:
  77. global $CONFIG;
  78. $plugins_path = $CONFIG->plugins_path
  79. // Using the $vars view parameter:
  80. $plugins_path = $vars['plugins_path'];
  81. Example of new code:
  82. .. code:: php
  83. $plugins_path = elgg_get_config('plugins_path');
  84. .. note::
  85. Compatible with 1.8
  86. .. note::
  87. See how the community_plugins plugin was updated: https://github.com/Elgg/community_plugins/commit/f233999bbd1478a200ee783679c2e2897c9a0483
  88. Language files
  89. --------------
  90. In Elgg 1.8 the language files needed to use the ``add_translation()`` function. In 1.9 it is enough to just return the array that was
  91. previously passed to the function as a parameter. Elgg core will use the file name (e.g. en.php) to tell which language the file contains.
  92. Example of the old way in ``languages/en.php``:
  93. .. code:: php
  94. $english = array(
  95. 'photos:all' => 'All photos',
  96. );
  97. add_translation('en', $english);
  98. Example of new way:
  99. .. code:: php
  100. return array(
  101. 'photos:all' => 'All photos',
  102. );
  103. .. warning::
  104. Not compatible with 1.8
  105. Notifications
  106. -------------
  107. One of the biggest changes in Elgg 1.9 is the notifications system. The new system allows more flexible and scalable way of sending notifications.
  108. Example of the old way:
  109. .. code:: php
  110. function photos_init() {
  111. // Tell core that we want to send notifications about new photos
  112. register_notification_object('object', 'photo', elgg_echo('photo:new'));
  113. // Register a handler that creates the notification message
  114. elgg_register_plugin_hook_handler('notify:entity:message', 'object', 'photos_notify_message');
  115. }
  116. /**
  117. * Set the notification message body
  118. *
  119. * @param string $hook Hook name
  120. * @param string $type Hook type
  121. * @param string $message The current message body
  122. * @param array $params Parameters about the photo
  123. * @return string
  124. */
  125. function photos_notify_message($hook, $type, $message, $params) {
  126. $entity = $params['entity'];
  127. $to_entity = $params['to_entity'];
  128. $method = $params['method'];
  129. if (elgg_instanceof($entity, 'object', 'photo')) {
  130. $descr = $entity->excerpt;
  131. $title = $entity->title;
  132. $owner = $entity->getOwnerEntity();
  133. return elgg_echo('photos:notification', array(
  134. $owner->name,
  135. $title,
  136. $descr,
  137. $entity->getURL()
  138. ));
  139. }
  140. return null;
  141. }
  142. Example of the new way:
  143. .. code:: php
  144. function photos_init() {
  145. elgg_register_notification_event('object', 'photo', array('create'));
  146. elgg_register_plugin_hook_handler('prepare', 'notification:publish:object:photo', 'photos_prepare_notification');
  147. }
  148. /**
  149. * Prepare a notification message about a new photo
  150. *
  151. * @param string $hook Hook name
  152. * @param string $type Hook type
  153. * @param Elgg_Notifications_Notification $notification The notification to prepare
  154. * @param array $params Hook parameters
  155. * @return Elgg_Notifications_Notification
  156. */
  157. function photos_prepare_notification($hook, $type, $notification, $params) {
  158. $entity = $params['event']->getObject();
  159. $owner = $params['event']->getActor();
  160. $recipient = $params['recipient'];
  161. $language = $params['language'];
  162. $method = $params['method'];
  163. // Title for the notification
  164. $notification->subject = elgg_echo('photos:notify:subject', array($entity->title), $language);
  165. // Message body for the notification
  166. $notification->body = elgg_echo('photos:notify:body', array(
  167. $owner->name,
  168. $entity->title,
  169. $entity->getExcerpt(),
  170. $entity->getURL()
  171. ), $language);
  172. // The summary text is used e.g. by the site_notifications plugin
  173. $notification->summary = elgg_echo('photos:notify:summary', array($entity->title), $language);
  174. return $notification;
  175. }
  176. .. warning::
  177. Not compatible with 1.8
  178. .. note::
  179. See how the community_plugins plugin was updated to use the new system: https://github.com/Elgg/community_plugins/commit/bfa356cfe8fb99ebbca4109a1b8a1383b70ff123
  180. Notifications can also be sent with the ``notify_user()`` function.
  181. It has however been updated to support three new optional parameters passed inside an array as the fifth parameter.
  182. The parameters give notification plugins more control over the notifications, so they should be included whenever possible. For example the bundled site_notifications plugin won't work properly if the parameters are missing.
  183. Parameters:
  184. - **object** The object that we are notifying about (e.g. ElggEntity or ElggAnnotation). This is needed so that notification plugins can provide a link to the object.
  185. - **action** String that describes the action that triggered the notification (e.g. "create", "update", etc).
  186. - **summary** String that contains a summary of the notification. (It should be more informative than the notification subject but less informative than the notification body.)
  187. Example of the old way:
  188. .. code:: php
  189. // Notify $owner that $user has added a $rating to an $entity created by him
  190. $subject = elgg_echo('rating:notify:subject');
  191. $body = elgg_echo('rating:notify:body', array(
  192. $owner->name,
  193. $user->name,
  194. $entity->title,
  195. $entity->getURL(),
  196. ));
  197. notify_user($owner->guid,
  198. $user->guid,
  199. $subject,
  200. $body
  201. );
  202. Example of the new way:
  203. .. code:: php
  204. // Notify $owner that $user has added a $rating to an $entity created by him
  205. $subject = elgg_echo('rating:notify:subject');
  206. $summary = elgg_echo('rating:notify:summary', array($entity->title));
  207. $body = elgg_echo('rating:notify:body', array(
  208. $owner->name,
  209. $user->name,
  210. $entity->title,
  211. $entity->getURL(),
  212. ));
  213. $params = array(
  214. 'object' => $rating,
  215. 'action' => 'create',
  216. 'summary' => $summary,
  217. );
  218. notify_user($owner->guid,
  219. $user->guid,
  220. $subject,
  221. $body,
  222. $params
  223. );
  224. .. note::
  225. Compatible with 1.8
  226. Adding items to the Activity listing
  227. ------------------------------------
  228. .. code:: php
  229. add_to_river('river/object/photo/create', 'create', $user_guid, $photo_guid);
  230. .. code:: php
  231. elgg_create_river_item(array(
  232. 'view' => 'river/object/photo/create',
  233. 'action_type' => 'create',
  234. 'subject_guid' => $user_guid,
  235. 'object_guid' => $photo_guid,
  236. ));
  237. You can also add the optional ``target_guid`` parameter which tells the target of the create action.
  238. If the photo would had been added for example into a photo album, we could add it by passing in also:
  239. .. code:: php
  240. 'target_guid' => $album_guid,
  241. .. warning::
  242. Not compatible with 1.8
  243. Entity URL handlers
  244. -------------------
  245. The ``elgg_register_entity_url_handler()`` function has been deprecated. In 1.9 you should use the ``'entity:url', 'object'`` plugin hook instead.
  246. Example of the old way:
  247. .. code:: php
  248. /**
  249. * Initialize the photo plugin
  250. */
  251. my_plugin_init() {
  252. elgg_register_entity_url_handler('object', 'photo', 'photo_url_handler');
  253. }
  254. /**
  255. * Returns the URL from a photo entity
  256. *
  257. * @param ElggEntity $entity
  258. * @return string
  259. */
  260. function photo_url_handler($entity) {
  261. return "photo/view/{$entity->guid}";
  262. }
  263. Example of the new way:
  264. .. code:: php
  265. /**
  266. * Initialize the photo plugin
  267. */
  268. my_plugin_init() {
  269. elgg_register_plugin_hook_handler('entity:url', 'object', 'photo_url_handler');
  270. }
  271. /**
  272. * Returns the URL from a photo entity
  273. *
  274. * @param string $hook 'entity:url'
  275. * @param string $type 'object'
  276. * @param string $url The current URL
  277. * @param array $params Hook parameters
  278. * @return string
  279. */
  280. function photo_url_handler($hook, $type, $url, $params) {
  281. $entity = $params['entity'];
  282. // Check that the entity is a photo object
  283. if ($entity->getSubtype() !== 'photo') {
  284. // This is not a photo object, so there's no need to go further
  285. return;
  286. }
  287. return "photo/view/{$entity->guid}";
  288. }
  289. .. warning::
  290. Not compatible with 1.8
  291. Web services
  292. ------------
  293. In Elgg 1.8 the web services API was included in core and methods were exposed
  294. using ``expose_function()``. To enable the same functionality for Elgg 1.9,
  295. enable the "Web services 1.9" plugin and replace all calls to
  296. ``expose_function()`` with ``elgg_ws_expose_function()``.
  297. From 1.7 to 1.8
  298. ===============
  299. Elgg 1.8 is the biggest leap forward in the development of Elgg since version 1.0.
  300. As such, there is more work to update core and plugins than with previous upgrades.
  301. There were a small number of API changes and following our standard practice,
  302. the methods we deprecated have been updated to work with the new API.
  303. The biggest changes are in the standardization of plugins and in the views system.
  304. Updating core
  305. -------------
  306. Delete the following core directories (same level as _graphics and engine):
  307. * _css
  308. * account
  309. * admin
  310. * dashboard
  311. * entities
  312. * friends
  313. * search
  314. * settings
  315. * simplecache
  316. * views
  317. .. warning::
  318. If you do not delete these directories before an upgrade, you will have problems!
  319. Updating plugins
  320. ----------------
  321. Use standardized routing with page handlers
  322. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  323. * All: /page_handler/all
  324. * User’s content: /page_handler/owner/:username
  325. * User’s friends' content: /page_handler/friends/:username
  326. * Single entity: /page_handler/view/:guid/:title
  327. * Added: /page_handler/add/:container_guid
  328. * Editing: /page_handler/edit/:guid
  329. * Group list: /page_handler/group/:guid/all
  330. Include page handler scripts from the page handler
  331. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  332. Almost every page handler should have a page handler script.
  333. (Example: ``bookmarks/all => mod/bookmarks/pages/bookmarks/all.php``)
  334. * Call ``set_input()`` for entity guids in the page handler and use ``get_input()`` in the page handler scripts.
  335. * Call ``gatekeeper()`` and ``admin_gatekeeper()`` in the page handler function if required.
  336. * The group URL should use the ``pages/:handler/owner.php`` script.
  337. * Page handlers should not contain HTML.
  338. * Update the URLs throughout the plugin. (Don't forget to remove ``/pg/``!)
  339. Use standardized page handlers and scripts
  340. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  341. * Store page handler scripts in ``mod/:plugin/pages/:page_handler/:page_name.php``
  342. * Use the content page layout in page handler scripts:
  343. .. code:: php
  344. $content = elgg_view_layout('content', $options);
  345. * Page handler scripts should not contain HTML.
  346. * Call ``elgg_push_breadcrumb()`` in the page handler scripts.
  347. * No need to set page owner if the URLs are in the standardized format.
  348. * For group content, check the container_guid by using elgg_get_page_owner_entity().
  349. The ``object/:subtype`` view
  350. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  351. * Make sure there are views for ``$vars['full_view'] == true`` and ``$vars['full_view'] == false``. ``$vars['full_view']`` replaced ``$vars['full]``.
  352. * Check for the object in ``$vars['entity']``. Use ``elgg_instance_of()`` to make sure it's the type of entity you want.
  353. * Return ``true`` to short circuit the view if the entity is missing or wrong.
  354. * Use ``elgg_view(‘object/elements/summary’, array(‘entity’ => $entity));`` and ``elgg_view_menu(‘entity’, array(‘entity’ => $entity));`` to help format. You should use very little markup in these views.
  355. Update action structure
  356. ~~~~~~~~~~~~~~~~~~~~~~~
  357. * Namespace action files and action names (example: ``mod/blog/actions/blog/save.php`` => ``action/blog/save``)
  358. * Use the following action URLs:
  359. * Add: ``action/:plugin/save``
  360. * Edit: ``action/:plugin/save``
  361. * Delete: ``action/:plugin/delete``
  362. * Make the delete action accept ``action/:handler/delete?guid=:guid`` so the metadata entity menu has the correct URL by default.
  363. Update deprecated functions
  364. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  365. * Functions deprecated in 1.7 will produce visible errors in 1.8.
  366. * See ``/engine/lib/deprecated-1.7.php`` for the full list.
  367. * You can also update functions deprecated in 1.8.
  368. * Many registration functions simply added an ``elgg_`` prefix for consistency, and should be easy to update.
  369. * See ``/engine/lib/deprecated-1.8.php`` for the full list.
  370. * You can set the debug level to “warning” to get visual reminders of deprecated functions.
  371. Update the widget views
  372. ~~~~~~~~~~~~~~~~~~~~~~~
  373. See the blog or file widgets for examples.
  374. Update the group profile module
  375. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  376. Use the blog or file plugins for examples. This will help with making your plugin themeable by the new CSS framework.
  377. Update forms
  378. ~~~~~~~~~~~~
  379. * Move form bodies to the ``forms/:action`` view to use Evan's new ``elgg_view_form``.
  380. * Use input views in form bodies rather than html. This helps with theming and future-proofing.
  381. * Add a function that prepares the form (see ``mod/file/lib/file.php`` for an example)
  382. * Make your forms sticky (see the file plugin's upload action and form prepare function).
  383. The forms API is discussed in more detail in :doc:`/guides/actions`.
  384. Clean up CSS/HTML
  385. ~~~~~~~~~~~~~~~~~
  386. We have added many CSS patterns to the base CSS file (modules, image block, spacing primitives). We encourage you to use these patterns and classes wherever possible. Doing so should:
  387. 1. Reduce maintenance costs, since you can delete most custom CSS.
  388. 2. Make your plugin more compatible with community themes.
  389. Look for patterns that can be moved into core if you need significant CSS.
  390. We use hyphens rather than underscores in classes/ids and encourage you do the same for consistency.
  391. If you do need your own CSS, you should use your own namespace, rather than ``elgg-``.
  392. Update manifest.xml
  393. ~~~~~~~~~~~~~~~~~~~
  394. * Use http://el.gg/manifest17to18 to automate this.
  395. * Don't use the "bundled" category with your plugins. That is only for plugins distributed with Elgg.
  396. Update settings and user settings views
  397. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  398. * The view for settings is now ``plugins/:plugin/settings`` (previously ``settings/:plugin/edit``).
  399. * The view for user settings is now ``plugins/:plugin/usersettings`` (previously ``usersettings/:plugin/edit``).