Updating plugins for Elgg 1.8

This doc is being rewritten as part of our docs revamp. Please join the effort!

Elgg 1.8 is the biggest leap forward in the development of Elgg since version 1.0. As such, there is more work to update plugins than with previous upgrades. There were a small number of API changes and following our standard practice, the methods we deprecated have been updated to work with the new API. The biggest changes are in the standardization of plugins and in the views system.

We have divided the changes into required and recommended sections. We also point you to plugins to use as examples. This is a wiki so please feel free to add hints or suggestions for other developers. Questions should be directed to the Elgg developers Google group or the Elgg community site forums.


Required

  1. Use standardized routing with page handlers - Example: Bookmarks plugin.
    1. Page handlers should accept the following standard URLs:
      1. All:page_handler/all
      2. User:page_handler/owner/<username>
      3. User friends':page_handler/friends/<username>
      4. Single entity:page_handler/view/<guid>/<title>
      5. Add:page_handler/add/<container_guid>
      6. Edit:page_handler/edit/<guid>
      7. Group list:page_handler/group/<guid>/all
    2. Include page handler scripts from the page handler. Almost every page handler should have a page handler script. (Example: bookmarks/all => mod/bookmarks/pages/bookmarks/all.php)
    3. Call set_input() for entity guids in the page handler and use get_input() in the page handler scripts.
    4. Call gatekeeper() and admin_gatekeeper() in the page handler function if required.
    5. The group URL should use the pages/<handler>/owner.php script.
    6. Page handlers should not contain HTML.
    7. If upgrading a 1.7 plugin, update the URLs throughout the plugin. (Don't forget to remove /pg/!)
  2. Use standardized page handlers and scripts - Example: Bookmarks plugin.
    1. Store page handler scripts in mod/<plugin>/pages/<page_handler>/<page_name>
    2. Use the content page layout in page handler scripts: $content = elgg_view_layout('content', $options);
    3. Page handler scripts should not contain HTML.
    4. Call elgg_push_breadcrumb() in the page handler scripts.
    5. No need to worry about setting the page owner if the URLs are in the standardized format.
    6. For group content, check the container_guid by using elgg_get_page_owner_entity().
  3. The object/<subtype> view - Example: Bookmarks plugin.
    1. Make sure there are views for $vars['full_view'] == true and $vars['full_view'] == false. $vars['full_view'] replaced $vars['full].
    2. Check for the object in $vars['entity']. Use elgg_instance_of() to make sure it's the type entity you want. Return true to short circuit the view if the entity is missing or wrong.
    3. Use the new object summary view and entity menu to help format. You should use very little markup in these views.
  4. Update action structure - Example: Bookmarks plugin.
    1. Namespace action files and action names (example: mod/blog/actions/blog/save.php => action/blog/save)
    2. Use the following action URLs:
      1. Add:action/plugin/save
      2. Edit:action/plugin/save
      3. Delete:action/plugin/delete
    3. Make the delete action accept action/<handler>/delete?guid=<guid> so the metadata entity menu has the correct URL by default.
  5. If updating a 1.7 plugin, replace calls to functions deprecated in 1.7 because these will produce visible errors on every load in 1.8.

Recommended

  1. Update the widget views (see the blog or file widgets)
  2. Update the group profile "widget" using blog or file plugins as example
  3. Update the forms
    1. Move form bodies to /forms/<handler>/<action> to use Evan's new elgg_view_form
    2. use input views in form bodies rather than html
    3. add a function that prepares the form (see mod/file/lib/file.php for example)
    4. integrate sticky forms (see the file plugin's upload action and form prepare function)
  4. Clean up CSS/HTML
    1. Should be able to remove most CSS as we have added many CSS patterns to the base CSS file (modules, image block, spacing primitives). Also look for patterns that can be moved into core if you need significant CSS.
    2. Use hyphens rather than underscores in classes/ids
  5. Update the manifest.xml file to the 1.8 format. Use http://el.gg/manifest17to18 to automate this.
    1. Don't use the "bundled" category with your plugins. That is for plugins distributed with Elgg.
  6. Update functions deprecated in 1.8.
    1. Many registration functions simply added an "elgg_" prefix for consistency.
    2. See /engine/lib/deprecated-1.8.php for the full list. You can also set the debug level to warning to get visual reminders of deprecated functions.
  7. Update settings and user settings views.
    1. The view for settings is now at "plugins/<plugin_id>/settings" (previously at "settings/<plugin_id>/edit").
    2. The view for user settings is now at plugins/<plugin_id>/usersettings" (previously at "usersettings/<plugin_id>/edit").

Search docs