guidelines.rst 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128
  1. Plugin coding guidelines
  2. ========================
  3. In addition to the Elgg Coding Standards, these are guidelines for creating plugins. Core plugins are being updated to this format and all plugin authors should follow these guidelines in their own plugins.
  4. .. seealso::
  5. Be sure to follow the :doc:`plugins/plugin-skeleton` for your plugin's layout.
  6. .. warning::
  7. :doc:`dont-modify-core`
  8. .. contents:: Contents
  9. :local:
  10. :depth: 1
  11. Use standardized routing with page handlers
  12. -------------------------------------------
  13. - Example: Bookmarks plugin
  14. - Page handlers should accept the following standard URLs:
  15. +---------------+-----------------------------------+
  16. | Purpose | URL |
  17. +===============+===================================+
  18. | All | page_handler/all |
  19. +---------------+-----------------------------------+
  20. | User | page_handler/owner/<username> |
  21. +---------------+-----------------------------------+
  22. | User friends’ | page_handler/friends/<username> |
  23. +---------------+-----------------------------------+
  24. | Single entity | page_handler/view/<guid>/<title> |
  25. +---------------+-----------------------------------+
  26. | Add | page_handler/add/<container_guid> |
  27. +---------------+-----------------------------------+
  28. | Edit | page_handler/edit/<guid> |
  29. +---------------+-----------------------------------+
  30. | Group list | page_handler/group/<guid>/owner |
  31. +---------------+-----------------------------------+
  32. - 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``)
  33. - Call ``set_input()`` for entity guids in the page handler and use ``get_input()`` in the page handler scripts.
  34. - Call ``elgg_gatekeeper()`` and ``elgg_admin_gatekeeper()`` in the page handler function if required.
  35. - The group URL should use the ``pages/<handler>/owner.php`` script.
  36. - Page handlers should not contain HTML.
  37. - If upgrading a 1.7 plugin, update the URLs throughout the plugin. (Don’t forget to remove ``/pg/``!)
  38. Use standardized page handlers and scripts
  39. ------------------------------------------
  40. - Example: Bookmarks plugin
  41. - Store page handler scripts in ``mod/<plugin>/pages/<page_handler>/<page_name>``
  42. - Use the content page layout in page handler scripts: ``$content = elgg_view_layout('content', $options);``
  43. - Page handler scripts should not contain HTML
  44. - Call ``elgg_push_breadcrumb()`` in the page handler scripts.
  45. - No need to worry about setting the page owner if the URLs are in the standardized format
  46. - For group content, check the ``container_guid`` by using ``elgg_get_page_owner_entity()``
  47. The object/<subtype> view
  48. -------------------------
  49. - Example: Bookmarks plugin
  50. - Make sure there are views for ``$vars[‘full’] == true`` and ``$vars[‘full’] == false``
  51. - 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.
  52. - Use the new list body and list metadata views to help format. You should use almost no markup in these views.
  53. - Update action structure - Example: Bookmarks plugin.
  54. - Namespace action files and action names (example: ``mod/blog/actions/blog/save.php`` => ``action/blog/save``)
  55. - Use the following action URLs:
  56. +---------+----------------------+
  57. | Purpose | URL |
  58. +=========+======================+
  59. | Add | action/plugin/save |
  60. +---------+----------------------+
  61. | Edit | action/plugin/save |
  62. +---------+----------------------+
  63. | Delete | action/plugin/delete |
  64. +---------+----------------------+
  65. - Make the delete action accept ``action/<handler>/delete?guid=<guid>`` so the metadata entity menu has the correct URL by default
  66. - 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
  67. Actions
  68. -------
  69. Actions are transient states to perform an action such as updating the database or sending a notification to a user. Used correctly, actions are secure and prevent against CSRF and XSS attacks.
  70. .. note::
  71. As of Elgg 1.7 all actions require action tokens.
  72. Action best practices
  73. ^^^^^^^^^^^^^^^^^^^^^
  74. Never call an action directly by saying:
  75. .. code:: html
  76. ...href="/mod/mymod/actions/myaction.php"
  77. This circumvents the security systems in Elgg.
  78. There is no need to include the ``engine/start.php`` file in your actions. Actions should never be called directly, so the engine will be started automatically when called correctly.
  79. Because actions are time-sensitive they are not suitable for links in emails or other delayed notifications. An example of this would be invitations to join a group. The clean way to create an invitation link is to create a page handler for invitations and email that link to the user. It is then the page handler's responsibility to create the action links for a user to join or ignore the invitation request.
  80. Directly calling a file
  81. -----------------------
  82. This is an easy one: **Don't do it**. With the exception of 3rd party application integration, there is not a reason to directly call a file in mods directory.
  83. Recommended
  84. -----------
  85. These points are good ideas, but are not yet in the official guidelines. Following these suggestions will help to keep your plugin consistent with Elgg core.
  86. - Update the widget views (see the blog or file widgets)
  87. - Update the group profile “widget” using blog or file plugins as example
  88. - Update the forms
  89. - Move form bodies to ``/forms/<handler>/<action>`` to use Evan’s new ``elgg_view_form()``
  90. - Use input views in form bodies rather than html
  91. - Add a function that prepares the form (see ``mod/file/lib/file.php`` for example)
  92. - Integrate sticky forms (see the file plugin’s upload action and form prepare function)
  93. - Clean up CSS/HTML
  94. - Should be able to remove almost all CSS (look for patterns that can be moved into core if you need CSS)
  95. - Use hyphens rather than underscores in classes/ids
  96. - Update the ``manifest.xml`` file to the 1.8 format. Use http://el.gg/manifest17to18 to automate this
  97. - Do not use the ``bundled`` category with your plugins. That is for plugins distributed with Elgg
  98. - Update functions deprecated in 1.8.
  99. - Many registration functions simply added an ``elgg_`` prefix for consistency
  100. - 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