Permalink
Browse files

docs(routing): clarify use of default_page_owner_handler in core

  • Loading branch information...
mrclay committed Jan 3, 2016
1 parent 9757d2e commit 5d647d18056bf1eef644dd30c9920df9a78d2f8d
Showing with 7 additions and 2 deletions.
  1. +4 −2 docs/guides/page-owner.rst
  2. +3 −0 engine/lib/pageowner.php
@@ -2,16 +2,18 @@ Page ownership
==============
One recurring task of any plugin will be to determine the page ownership in order to decide which actions are allowed or not. Elgg has a number of functions related to page ownership and also offers plugin developers flexibility by letting the plugin handle page ownership requests as well.
Determining the owner of a page can be determined with ``elgg_get_page_owner_guid()``, which will return the GUID of the owner. Alternatively, ``elgg_get_page_owner_entity()`` will retrieve the whole page owner entity. If the page already knows who the page owner is, but the system doesn't, the it be can set by passing the GUID to ``elgg_set_page_owner_guid($guid)``.
Custom page owner handlers
--------------------------
Plugin developers can create page owner handlers, which could be necessary in certain cases, for example when integrating third party functionality. The handler will be a function which will need to get registered with ``elgg_register_plugin_hook_handler('page_owner', 'system', 'your_page_owner_function_name');`` . The handler will only need to return a value (an integer GUID) when it knows for certain who the page owner is.
By default, the system determines the page_owner from the following elements:
By default, the system uses ``default_page_owner_handler()`` to determine the page_owner from the following elements:
- The ``username`` URL parameter
- The ``owner_guid`` URL parameter
- The URL path
It then passes off to any page owner handlers defined using the :ref:`plugin hook <design/events#plugin-hooks>`. If no page owner can be determined, the page owner is set to 0, which is the same as the logged out user.
It then passes off to any page owner handlers defined using the :ref:`plugin hook <design/events#plugin-hooks>`. If no page owner can be determined, the page owner is set to 0, which is the same as the logged out user.
View
@@ -10,6 +10,8 @@
/**
* Gets the guid of the entity that owns the current page.
*
* @see default_page_owner_handler Used to guess the page owner if it's not been set.
*
* @param int $guid Optional parameter used by elgg_set_page_owner_guid().
*
* @return int The current page owner guid (0 if none).
@@ -32,6 +34,7 @@ function elgg_get_page_owner_guid($guid = 0) {
}
// return guid of page owner entity
// Note: core registers default_page_owner_handler() to handle this hook.
$guid = (int)elgg_trigger_plugin_hook('page_owner', 'system', null, 0);
if ($guid) {

0 comments on commit 5d647d1

Please sign in to comment.