Engine/Controllers/PageHandler

This page is up-to-date for Elgg 1.8.

Page handling

Elgg offers a facility to manage your plugin pages via a page handler, enabling custom urls like http://yoursite/your_plugin/section. To add a page handler to a plugin, a handler function needs to be registered in the plugin's start.php file with elgg_register_page_handler():

elgg_register_page_handler('your_plugin', 'your_plugin_page_handler');

The plugin's page handler is passed a single parameter: an array containing the sections of the URL exploded by '/'. With this information the handler will be able to apply any logic necessary, for example loading the appropriate view and returning its contents.

Code flow

Pages in plugins should be served only through page handlers, stored in pages/ of your plugin's directory and do not need to include or require Elgg's engine/start.php file. The purpose of these files are to knit together output from different views to form the page that the user sees. The program flow is something like this:

1. A user requests /plugin_name/section/entity
2. Elgg checks if 'plugin_name' is registered to a page handler and calls that function, passing array('section', 'entity') as the first argument.
3. The page handler function determines which page to display, optionally sets some values, and then includes the correct page under plugin_name/pages/plugin_name/.
4. The included file combines many separate views, calls formatting functions like elgg_view_layout() and elgg_view_page(), and then echos the final output.
5. The user sees a fully rendered page.

There is no syntax enforced on the URLs, but Elgg's coding standards suggests a certain format.

Pre-1.8 notes

In Elgg 1.7 and prior, a /pg/ prefix was required on all urls in order to be passed through the page handler. So instead of /plugin_name/section/entity, the url would be /pg/plugin_name/section/entity.

Furthermore, the elgg_ prefix was added to the registration function in 1.8. If developing for 1.7 or prior, you'll need to use register_page_handler() instead.