From 2.1 to 2.2
===============

.. contents:: Contents
   :local:
   :depth: 1

Deprecated APIs
---------------

 * ``elgg.ui.river`` JavaScript library: Remove calls to ``elgg_load_js('elgg.ui.river')`` from plugin code. Update ``core/river/filter`` and ``forms/comment/save``, if overwritten, to require component AMD modules
 * ``elgg.ui.popupOpen()`` and ``elgg.ui.popupClose()`` methods in ``elgg.ui`` JS library: Use ``elgg/popup`` module instead.
 * ``lightbox.js`` library: Do not use ``elgg_load_js('lightbox.js');`` unless your code references deprecated ``elgg.ui.lightbox`` namespace. Use ``elgg/lightbox`` AMD module instead.
 * ``elgg.embed`` library and ``elgg.embed`` object: Do not use ``elgg_load_js('elgg.embed')``. Use ``elgg/embed`` AMD module instead
 * Accessing ``icons_sizes`` config value directly: Use ``elgg_get_icon_sizes()``
 * ``can_write_to_container()``: Use ``ElggEntity::canWriteToContainer()``

Deprecated Views
----------------

 * ``elgg/ui.river.js`` is deprecated: Do not rely on simplecache URLs to work.
 * ``groups/js`` is deprecated: Use ``groups/navigation`` AMD module as a menu item dependency for "feature" and "unfeature" menu items instead.
 * ``lightbox/settings.js`` is deprecated: Use ``getOptions, ui.lightbox`` JS plugin hook or ``data-colorbox-opts`` attribute.
 * ``elgg/ckeditor/insert.js`` is deprecated: You no longer need to include it, hook registration takes place in ``elgg/ckeditor`` module
 * ``embed/embed.js`` is deprecated: Use ``elgg/embed`` AMD module.

Added ``elgg/popup`` module
---------------------------

New :doc:`elgg/popup module </guides/javascript>` can be used to build out more complex trigger-popup interactions, including binding custom anchor types and opening/closing popups programmatically.

Added ``elgg/lightbox`` module
------------------------------

New :doc:`elgg/lightbox module </guides/javascript>` can be used to open and close the lightbox programmatically.

Added ``elgg/embed`` module
---------------------------

Even though rarely necessary, ``elgg/embed`` AMD module can be used to access the embed methods programmatically. The module bootstraps itself when necessary and is unlikely to require further decoration.

New API for handling entity icons
---------------------------------

 * ``ElggEntity`` now implements ``\Elgg\EntityIcon`` interface
 * ``elgg_get_icon_sizes()`` - return entity type/subtype specific icon sizes
 * ``ElggEntity::saveIconFromUploadedFile()`` - creates icons from an uploaded file
 * ``ElggEntity::saveIconFromLocalFile()`` - creates icons from a local file
 * ``ElggEntity::saveIconFromElggFile()`` - creates icons from an instance of ``ElggFile``
 * ``ElggEntity::getIcon()`` - returns an instanceof ``ElggIcon`` that points to entity icon location on filestore (this may be just a placeholder, use ``ElggEntity::hasIcon()`` to validate if file has been written)
 * ``ElggEntity::deleteIcon()`` - deletes entity icons
 * ``ElggEntity::getIconLastChange()`` - return modified time of the icon file
 * ``ElggEntity::hasIcon()`` - checks if an icon with given size has been created
 * ``elgg_get_embed_url()`` - can be used to return an embed URL for an entity's icon (served via `/serve-icon` handler)

User avatars are now served via ``serve-file`` handler. Plugins should start using ``elgg_get_inline_url()`` and note that:

 * ``/avatar/view`` page handler and resource view have been deprecated
 * ``/mod/profile/icondirect.php`` file has been deprecated
 * ``profile_set_icon_url()`` is no longer registered as a callback for ``"entity:icon:url","user"`` plugin hook

Group avatars are now served via ``serve-file`` handler. Plugins should start using ``elgg_get_inline_url()`` and note that:

 * ``groupicon`` page handler (``groups_icon_handler()``) has been deprecated
 * ``/mod/groups/icon.php`` file has been deprecated

File entity thumbs and downloads are now served via ``serve-file`` handler. Plugins should start using ``elgg_get_inline_url()`` and ``elgg_get_download_url()`` and note that:

 * ``file/download`` page handler and resource view have been deprecated
 * ``mod/file/thumbnail.php`` file has been deprecated
 * Several views have been updated to use new download URLs, including:

   - ``mod/file/views/default/file/specialcontent/audio/default.php``
   - ``mod/file/views/default/file/specialcontent/image/default.php``
   - ``mod/file/views/default/resources/file/view.php``
   - ``mod/file/views/rss/file/enclosure.php``

Removed APIs
------------

Just a warning that the private entity cache functions (e.g. ``_elgg_retrieve_cached_entity``) have been removed. Some plugins may have been using them. Plugins should not use private APIs as they will more often be removed without notice.

Improved ``elgg/ckeditor`` module
---------------------------------

:doc:`elgg/ckeditor module </guides/javascript>` can now be used to add WYSIWYG to a textarea programmatically with ``elgg/ckeditor#bind``.
