hooks-list.rst 18 KB

  1. List of plugin hooks in core
  2. ############################
  3. .. contents:: Contents
  4. :local:
  5. :depth: 1
  6. System hooks
  7. ============
  8. **email, system**
  9. Triggered when sending email. ``$params`` contains:
  10. * to
  11. * from
  12. * subject
  13. * body
  14. * headers
  15. * params
  16. **page_owner, system**
  17. Filter the page_owner for the current page. No options are passed.
  18. **siteid, system**
  19. **gc, system**
  20. Allows plugins to run garbage collection for ``$params['period']``.
  21. **unit_test, system**
  22. Add a Simple Test test. (Deprecated.)
  23. **diagnostics:report, system**
  24. Filter the output for the diagnostics report download.
  25. **search_types, get_types**
  26. **cron, <period>**
  27. Triggered by cron for each period.
  28. **validate, input**
  29. Filter GET and POST input. This is used by ``get_input()`` to sanitize user input.
  30. **geocode, location**
  31. Deprecated as of 1.9.
  32. **diagnostics:report, system**
  33. Filters the output for a diagnostic report.
  34. **debug, log**
  35. Triggered by the Logger. Return false to stop the default logging method. ``$params`` includes:
  36. * level - The debug level. One of:
  37. * ``Elgg_Logger::OFF``
  38. * ``Elgg_Logger::ERROR``
  39. * ``Elgg_Logger::WARNING``
  40. * ``Elgg_Logger::NOTICE``
  41. * ``Elgg_Logger::INFO``
  42. * msg - The message
  43. * display - Should this message be displayed?
  44. **format, friendly:title**
  45. Formats the "friendly" title for strings. This is used for generating URLs.
  46. **format, friendly:time**
  47. Formats the "friendly" time for the timestamp ``$params['time']``.
  48. **format, strip_tags**
  49. Filters a string to remove tags. The original string is passed as ``$params['original_string']``
  50. and an optional set of allowed tags is passed as ``$params['allowed_tags']``.
  51. **output:before, page**
  52. In ``elgg_view_page()``, this filters ``$vars`` before it's passed to the page shell
  53. view (``page/<page_shell>``). To stop sending the X-Frame-Options header, unregister the
  54. handler ``_elgg_views_send_header_x_frame_options()`` from this hook.
  55. **output, page**
  56. In ``elgg_view_page()``, this filters the output return value.
  57. **output:before, layout**
  58. In ``elgg_view_layout()``, filters ``$params`` before it's passed to the layout view.
  59. **output:after, layout**
  60. In ``elgg_view_layout()``, filters the return value of the layout view.
  61. **output, ajax**
  62. Triggered in the ajax forward hook that is called for ajax requests. Allows plugins to alter the
  63. output returned, including the forward URL, system messages, and errors.
  64. **parameters, menu:<menu_name>**
  65. Triggered by ``elgg_view_menu()``. Used to change menu variables (like sort order) before it is generated.
  66. **register, menu:<menu_name>**
  67. Triggered by ``elgg_view_menu()``. Used to add dynamic menu items.
  68. **prepare, menu:<menu_name>**
  69. Trigger by ``elgg_view_menu()``. Used to sort, add, remove, and modify menu items.
  70. **creating, river**
  71. Triggered before a river item is created. Return false to prevent river item from being created.
  72. **simplecache:generate, <view>**
  73. Triggered when generating the cached content of a view.
  74. **get, subscriptions**
  75. Filter notification subscriptions for users for the Elgg_Notifications_Event ``$params['event']``.
  76. Return an array like:
  77. .. code:: php
  78. array(
  79. <user guid> => array('subscription', 'types'),
  80. <user_guid2> => array('email', 'sms', 'ajax')
  81. );
  82. **prepare, breadcrumbs**
  83. In elgg_get_breadcrumbs(), this filters the registered breadcrumbs before
  84. returning them, allowing a plugin to alter breadcrumb strategy site-wide.
  85. **add, river**
  86. User hooks
  87. ==========
  88. **usersettings:save, user**
  89. Triggered in the aggregate action to save user settings. Return false prevent sticky
  90. forms from being cleared.
  91. **access:collections:write, user**
  92. Filters an array of access permissions that the user ``$params['user_id']`` is allowed to save
  93. content with. Permissions returned are of the form (id => 'Human Readable Name').
  94. **registeruser:validate:username, all**
  95. Return boolean for if the string in ``$params['username']`` is valid for a username.
  96. **registeruser:validate:password, all**
  97. Return boolean for if the string in ``$params['password']`` is valid for a password.
  98. **registeruser:validate:email, all**
  99. Return boolean for if the string in ``$params['email']`` is valid for an email address.
  100. **register, user**
  101. Triggered by the ``register`` action after the user registers. Return ``false`` to delete the user.
  102. Note the function ``register_user`` does *not* trigger this hook.
  103. **login:forward, user**
  104. Filters the URL to which the user will be forwarded after login.
  105. **find_active_users, system**
  106. Return the number of active users.
  107. **status, user**
  108. Triggered by The Wire when adding a post.
  109. **username:character_blacklist, user**
  110. Filters the string of blacklisted characters used to validate username during registration.
  111. The return value should be a string consisting of the disallowed characters. The default
  112. string can be found from ``$params['blacklist']``.
  113. Object hooks
  114. ============
  115. **comments, <entity_type>**
  116. Triggered in ``elgg_view_comments()``. If returning content, this overrides the
  117. ``page/elements/comments`` view.
  118. **comments:count, <entity_type>**
  119. Return the number of comments on ``$params['entity']``.
  120. **likes:count, <entity_type>**
  121. Return the number of likes for ``$params['entity']``.
  122. Action hooks
  123. ============
  124. **action, <action>**
  125. Triggered before executing action scripts. Return false to abort action.
  126. **action_gatekeeper:permissions:check, all**
  127. Triggered after a CSRF token is validated. Return false to prevent validation.
  128. **action_gatekeeper:upload_exceeded_msg, all**
  129. Triggered when a POST exceeds the max size allowed by the server. Return an error message
  130. to display.
  131. **forward, <reason>**
  132. Filter the URL to forward a user to when ``forward($url, $reason)`` is called.
  133. .. _guides/hooks-list#permission-hooks:
  134. Permission hooks
  135. ================
  136. **container_permissions_check, <entity_type>**
  137. Return boolean for if the user ``$params['user']`` can use the entity ``$params['container']``
  138. as a container for an entity of ``<entity_type>`` and subtype ``$params['subtype']``.
  139. **permissions_check, <entity_type>**
  140. Return boolean for if the user ``$params['user']`` can edit the entity ``$params['entity']``.
  141. **permissions_check:delete, <entity_type>**
  142. Return boolean for if the user ``$params['user']`` can delete the entity ``$params['entity']``. Defaults to ``$entity->canEdit()``.
  143. **permissions_check, widget_layout**
  144. Return boolean for if ``$params['user']`` can edit the widgets in the context passed as
  145. ``$params['context']`` and with a page owner of ``$params['page_owner']``.
  146. **permissions_check:metadata, <entity_type>**
  147. Return boolean for if the user ``$params['user']`` can edit the metadata ``$params['metadata']``
  148. on the entity ``$params['entity']``.
  149. **permissions_check:comment, <entity_type>**
  150. Return boolean for if the user ``$params['user']`` can comment on the entity ``$params['entity']``.
  151. **permissions_check:annotate:<annotation_name>, <entity_type>**
  152. Return boolean for if the user ``$params['user']`` can create an annotation ``<annotation_name>`` on the
  153. entity ``$params['entity']``. If logged in, the default is true.
  154. .. note:: This is called before the more general ``permissions_check:annotate`` hook, and its return value is that hook's initial value.
  155. **permissions_check:annotate, <entity_type>**
  156. Return boolean for if the user ``$params['user']`` can create an annotation ``$params['annotation_name']``
  157. on the entity ``$params['entity']``. if logged in, the default is true.
  158. .. warning:: This is functions differently than the ``permissions_check:metadata`` hook by passing the annotation name instead of the metadata object.
  159. **permissions_check:annotation**
  160. Return boolean for if the user in ``$params['user']`` can edit the annotation ``$params['annotation']`` on the
  161. entity ``$params['entity']``. The user can be null.
  162. **fail, auth**
  163. Return the failure message if authentication failed. An array of previous PAM failure methods
  164. is passed as ``$params``.
  165. **api_key, use**
  166. Triggered by ``api_auth_key()``. Returning false prevents the key from being authenticated.
  167. **access:collections:read, user**
  168. Filters an array of access IDs that the user ``$params['user_id']`` can see.
  169. .. warning:: The handler needs to either not use parts of the API that use the access system (triggering the hook again) or to ignore the second call. Otherwise, an infinite loop will be created.
  170. **access:collections:write, user**
  171. Filters an array of access IDs that the user ``$params['user_id']`` can write to. In
  172. get_write_access_array(), this hook filters the return value, so it can be used to alter
  173. the available options in the input/access view. For core plugins, the value "input_params"
  174. has the keys "entity" (ElggEntity|false), "entity_type" (string), "entity_subtype" (string),
  175. "container_guid" (int) are provided. An empty entity value generally means the form is to
  176. create a new object.
  177. .. warning:: The handler needs to either not use parts of the API that use the access system (triggering the hook again) or to ignore the second call. Otherwise, an infinite loop will be created.
  178. **access:collections:addcollection, collection**
  179. Triggered after an access collection ``$params['collection_id']`` is created.
  180. **access:collections:deletecollection, collection**
  181. Triggered before an access collection ``$params['collection_id']`` is deleted.
  182. Return false to prevent deletion.
  183. **access:collections:add_user, collection**
  184. Triggered before adding user ``$params['user_id']`` to collection ``$params['collection_id']``.
  185. Return false to prevent adding.
  186. **access:collections:remove_user, collection**
  187. Triggered before removing user ``$params['user_id']`` to collection ``$params['collection_id']``.
  188. Return false to prevent removal.
  189. **get_sql, access**
  190. Filters the SQL clauses used in ``_elgg_get_access_where_sql()``.
  191. .. _guides/hooks-list#views:
  193. =====
  194. **view_vars, <view_name>**
  195. Filters the ``$vars`` array passed to the view
  196. **view, <view_name>**
  197. Filters the returned content of the view
  198. **layout, page**
  199. In ``elgg_view_layout()``, filters the layout name
  200. **shell, page**
  201. In ``elgg_view_page()``, filters the page shell name
  202. **head, page**
  203. In ``elgg_view_page()``, filters ``$vars['head']``
  204. Files
  205. =====
  206. **mime_type, file**
  207. Return the mimetype for the filename ``$params['filename']`` with original filename ``$params['original_filename']``
  208. and with the default detected mimetype of ``$params['default']``.
  209. **simple_type, file**
  210. In ``elgg_get_file_simple_type()``, filters the return value. The hook uses ``$params['mime_type']``
  211. (e.g. ``application/pdf`` or ``image/jpeg``) and determines an overall category like
  212. ``document`` or ``image``. The bundled file plugin and other-third party plugins usually store
  213. ``simpletype`` metadata on file entities and make use of it when serving icons and constructing
  214. ``ege*`` filters and menus.
  215. .. _guides/hooks-list#other:
  216. Other
  217. =====
  218. **config, comments_per_page**
  219. Filters the number of comments displayed per page. Default is 25.
  220. **default, access**
  221. In get_default_access(), this hook filters the return value, so it can be used to alter
  222. the default value in the input/access view. For core plugins, the value "input_params" has
  223. the keys "entity" (ElggEntity|false), "entity_type" (string), "entity_subtype" (string),
  224. "container_guid" (int) are provided. An empty entity value generally means the form is to
  225. create a new object.
  226. **entity:icon:url, <entity_type>**
  227. Triggered when entity icon URL is requested, see :ref:`entity icons <guides/database#entity-icons>`. Callback should
  228. return URL for the icon of size ``$params['size']`` for the entity ``$params['entity']``.
  229. Following parameters are available through the ``$params`` array:
  230. entity
  231. Entity for which icon url is requested.
  232. viewtype
  233. The type of :ref:`view <guides/views#listing-entities>` e.g. ``'default'`` or ``'json'``.
  234. size
  235. Size requested, see :ref:`entity icons <guides/database#entity-icons>` for possible values.
  236. Example on how one could default to a Gravatar icon for users that
  237. have not yet uploaded an avatar:
  238. .. code:: php
  239. // Priority 600 so that handler is triggered after avatar handler
  240. elgg_register_plugin_hook_handler('entity:icon:url', 'user', 'gravatar_icon_handler', 600);
  241. /**
  242. * Default to icon from gravatar for users without avatar.
  243. */
  244. function gravatar_icon_handler($hook, $type, $url, $params) {
  245. // Allow users to upload avatars
  246. if ($params['entity']->icontime) {
  247. return $url;
  248. }
  249. // Generate gravatar hash for user email
  250. $hash = md5(strtolower(trim($params['entity']->email)));
  251. // Default icon size
  252. $size = '150x150';
  253. // Use configured size if possible
  254. $config = elgg_get_config('icon_sizes');
  255. $key = $params['size'];
  256. if (isset($config[$key])) {
  257. $size = $config[$key]['w'] . 'x' . $config[$key]['h'];
  258. }
  259. // Produce URL used to retrieve icon
  260. return "http://www.gravatar.com/avatar/$hash?s=$size";
  261. }
  262. **entity:url, <entity_type>**
  263. Return the URL for the entity ``$params['entity']``. Note: Generally it is better to override the
  264. ``getUrl()`` method of ElggEntity. This hook should be used when it's not possible to subclass
  265. (like if you want to extend a bundled plugin without overriding many views).
  266. **to:object, <entity_type|metadata|annotation|relationship|river_item>**
  267. Converts the entity ``$params['entity']`` to a StdClass object. This is used mostly for exporting
  268. entity properties for portable data formats like JSON and XML.
  269. **extender:url, <annotation|metadata>**
  270. Return the URL for the annotation or metadatum ``$params['extender']``.
  271. **file:icon:url, override**
  272. Override a file icon URL.
  273. **is_member, group**
  274. Return boolean for if the user ``$params['user']`` is a member of the group ``$params['group']``.
  275. **entity:annotate, <entity_type>**
  276. Triggered in ``elgg_view_entity_annotations()``, which is called by ``elgg_view_entity()``. Can
  277. be used to add annotations to all full entity views.
  278. **usersetting, plugin**
  279. Filter user settings for plugins. ``$params`` contains:
  280. - ``user`` - An ElggUser instance
  281. - ``plugin`` - An ElggPlugin instance
  282. - ``plugin_id`` - The plugin ID
  283. - ``name`` - The name of the setting
  284. - ``value`` - The value to set
  285. **setting, plugin**
  286. Filter plugin settings. ``$params`` contains:
  287. - ``plugin`` - An ElggPlugin instance
  288. - ``plugin_id`` - The plugin ID
  289. - ``name`` - The name of the setting
  290. - ``value`` - The value to set
  291. **relationship:url, <relationship_name>**
  292. Filter the URL for the relationship object ``$params['relationship']``.
  293. **profile:fields, group**
  294. Filter an array of profile fields. The result should be returned as an array in the format
  295. ``name => input view name``. For example:
  296. .. code:: php
  297. array(
  298. 'about' => 'longtext'
  299. );
  300. **profile:fields, profile**
  301. Filter an array of profile fields. The result should be returned as an array in the format
  302. ``name => input view name``. For example:
  303. .. code:: php
  304. array(
  305. 'about' => 'longtext'
  306. );
  307. **widget_settings, <widget_handler>**
  308. Triggered when saving a widget settings ``$params['params']`` for widget ``$params['widget']``.
  309. If handling saving the settings, the handler should return true to prevent the default code from running.
  310. **get_list, default_widgets**
  311. Filters a list of default widgets to add for newly registered users. The list is an array
  312. of arrays in the format:
  313. .. code:: php
  314. array(
  315. 'event' => $event,
  316. 'entity_type' => $entity_type,
  317. 'entity_subtype' => $entity_subtype,
  318. 'widget_context' => $widget_context
  319. )
  320. **rest, init**
  321. Triggered by the web services rest handler. Plugins can set up their own authentication
  322. handlers, then return true to prevent the default handlers from being registered.
  323. **public_pages, walled_garden**
  324. Filter the URLs that are can be seen by logged out users if Walled Garden is
  325. enabled. ``$value`` is an array of regex strings that will allow access if matched.
  326. **volatile, metadata**
  327. Triggered when exporting an entity through the export handler. This is rare.
  328. This allows handler to handle any volatile (non-persisted) metadata on the entity.
  329. It's preferred to use the ``to:object, <type>`` hook.
  330. **maintenance:allow, url**
  331. Return boolean if the URL ``$params['current_url']`` and the path ``$params['current_path']``
  332. is allowed during maintenance mode.
  333. **robots.txt, site**
  334. Filter the robots.txt values for ``$params['site']``.
  335. **config, amd**
  336. Filter the AMD config for the requirejs library.
  337. Plugins
  338. =======
  339. Embed
  340. -----
  341. **embed_get_items, <active_section>**
  342. **embed_get_sections, all**
  343. **embed_get_upload_sections, all**
  344. HTMLawed
  345. --------
  346. **allowed_styles, htmlawed**
  347. Filter the HTMLawed allowed style array.
  348. **config, htmlawed**
  349. Filter the HTMLawed config array.
  350. Members
  351. -------
  352. **members:list, <page_segment>**
  353. To handle the page ``/members/$page_segment``, register for this hook and return the HTML of the list.
  354. **members:config, tabs**
  355. This hook is used to assemble an array of tabs to be passed to the navigation/tabs view
  356. for the members pages.
  357. Twitter API
  358. -----------
  359. **authorize, twitter_api**
  360. Triggered when a user is authorizes Twitter for a login. ``$params['token']`` contains the Twitter
  361. authorization token.
  362. Reported Content
  363. ----------------
  364. **reportedcontent:add, system**
  365. Triggered after adding the reported content object ``$params['report']``. Return false to delete report.
  366. **reportedcontent:archive, system**
  367. Triggered before archiving the reported content object ``$params['report']``. Return false to prevent archiving.
  368. **reportedcontent:delete, system**
  369. Triggered before deleting the reported content object ``$params['report']``. Return false to prevent deleting.
  370. Search
  371. ------
  372. **search, <type>:<subtype>**
  373. Filter more granular search results than searching by type alone. Must return an array with ``count`` as the
  374. total count of results and ``entities`` an array of ElggUser entities.
  375. **search, tags**
  376. **search, <type>**
  377. Filter the search for entities for type ``$type``. Must return an array with ``count`` as the
  378. total count of results and ``entities`` an array of ElggUser entities.
  379. **search_types, get_types**
  380. Filter an array of search types. This allows plugins to add custom types that don't correspond
  381. directly to entities.
  382. **search_types, get_queries**
  383. Before a search this filters the types queried. This can be used to reorder
  384. the display of search results.