plugins.rst 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  1. Plugins
  2. #######
  3. Plugins must provide a start.php and manifest.xml file in the plugin root
  4. in order to be recognized by Elgg.
  5. start.php
  6. =========
  7. The start.php file bootstraps plugin by registering event listeners and plugin
  8. hooks.
  9. activate.php, deactivate.php
  10. ============================
  11. The activate.php and deactivate.php files contain procedural code that will run
  12. upon plugin activation and deactivation. Use these files to perform one-time
  13. events such as registering a persistent admin notice, registering subtypes, or performing
  14. garbage collection when deactivated.
  15. manifest.xml
  16. ============
  17. Elgg plugins are required to have a ``manifest.xml`` file in the root of a plugin.
  18. The ``manifest.xml`` file includes information about the plugin itself, requirements to run the plugin, and optional information including where to display the plugin in the admin area and what APIs the plugin provides.
  19. Syntax
  20. ------
  21. The manifest file is a standard XML file in UTF-8. Everything is a child of the ``<plugin_manifest>`` element.
  22. .. code:: xml
  23. <?xml version="1.0" encoding="UTF-8" ?>
  24. <plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
  25. The manifest syntax is as follows:
  26. .. code:: xml
  27. <name>value</name>
  28. Many elements can contain children attributes:
  29. .. code:: xml
  30. <parent_name>
  31. <child_name>value</child_name>
  32. <child_name_2>value_2</child_name_2>
  33. </parent_name>
  34. Required Elements
  35. -----------------
  36. All plugins are required to define the following elements in their manifest files:
  37. * id - This has the name as the directory that the plugin uses.
  38. * name - The display name of the plugin.
  39. * author - The name of the author who wrote the plugin.
  40. * version - The version of the plugin.
  41. * description - A description of the what the plugin provides, its features, and other relevant information
  42. * requires - Each plugin must specify the release of Elgg it was developed for. See the plugin Dependencies page for more information.
  43. Available Elements
  44. ------------------
  45. In addition to the require elements above, the follow elements are available to use:
  46. * blurb - A short description of the plugin.
  47. * category - The category of the plugin. It is recommended to follow the [[Plugin_Guidelines|plugin guidelines]] and use one of the defined categories. There can be multiple entries.
  48. * conflicts - Specifies that the plugin conflicts with a certain system configuration.
  49. * copyright - The plugin's copyright information.
  50. * license - The plugin's license information.
  51. * provides - Specifies that this plugin provides the same functionality as another Elgg plugin or a PHP extension.
  52. * screenshot - Screenshots of the plugin. There can be multiple entries. See the advanced example for syntax.
  53. * suggests - Parallels the requires system, but doesn't affect if the plugin can be enabled. Used to suggest other plugins that interact or build on the plugin.
  54. * website - A link to the website for the plugin.
  55. .. seealso::
  56. :doc:`plugins/dependencies`
  57. Simple Example
  58. --------------
  59. This manifest file is the bare minimum a plugin must have.
  60. .. code:: xml
  61. <?xml version="1.0" encoding="UTF-8"?>
  62. <plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
  63. <name>Example Manifest</name>
  64. <author>Elgg</author>
  65. <version>1.0</version>
  66. <description>This is a simple example of a manifest file. In this example, there are not screenshots, dependencies, or additional information about the plugin.</description>
  67. <requires>
  68. <type>elgg_release</type>
  69. <version>1.9</version>
  70. </requires>
  71. </plugin_manifest>
  72. Advanced example
  73. ----------------
  74. This example uses all of the available elements:
  75. .. code:: xml
  76. <?xml version="1.0" encoding="UTF-8"?>
  77. <plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
  78. <name>Example Manifest</name>
  79. <author>Brett Profitt</author>
  80. <version>1.0</version>
  81. <blurb>This is an example manifest file.</blurb>
  82. <description>This is a simple example of a manifest file. In this example, there are many options used, including screenshots, dependencies, and additional information about the plugin.</description>
  83. <website>http://www.elgg.org/</website>
  84. <copyright>(C) Brett Profitt 2014</copyright>
  85. <license>GNU Public License version 2</license>
  86. <category>3rd_party_integration</category>
  87. <requires>
  88. <type>elgg_release</type>
  89. <version>1.9.1</version>
  90. </requires>
  91. <!-- The path is relative to the plugin's root. -->
  92. <screenshot>
  93. <description>Elgg profile.</description>
  94. <path>screenshots/profile.png</path>
  95. </screenshot>
  96. <provides>
  97. <type>plugin</type>
  98. <name>example_plugin</name>
  99. <version>1.5</version>
  100. </provides>
  101. <suggests>
  102. <type>plugin</type>
  103. <name>twitter</name>
  104. <version>1.0</version>
  105. </suggests>
  106. </plugin_manifest>
  107. Related
  108. =======
  109. .. toctree::
  110. :maxdepth: 1
  111. plugins/plugin-skeleton
  112. plugins/dependencies