Same filename and directory in other branches
This is an example outlining how a module can be used to display a custom page at a given URL.
File
developer/examples/page_example.moduleView source
<?php
/**
* @file
* This is an example outlining how a module can be used to display a
* custom page at a given URL.
*/
/**
* Implementation of hook_help().
*
* Throughout Drupal, hook_help() is used to display help text at the top of
* pages. Some other parts of Drupal pages get explanatory text from these hooks
* as well. We use it here to provide a description of the module on the
* module administration page. This example also illustrates how to add help
* text to the pages your module defines.
*/
function page_example_help($section) {
switch ($section) {
case 'admin/modules#description':
// This description is shown in the listing at admin/modules.
return t('An example module showing how to define a page to be displayed to the user at a given URL.');
case 'foo':
// Here is some help text for a custom page.
return t('This sentence contains all the letters in the English alphabet.');
}
}
/**
* Implementation of hook_perm().
*
* Since the access to our new custom pages will be granted based on
* special permissions, we need to define what those permissions are here.
* This ensures that they are available to enable on the user role
* administration pages.
*/
function page_example_perm() {
return array(
'access foo',
'access baz',
);
}
/**
* Implementation of hook_menu().
*
* You must implement hook_menu() to emit items to place in the main menu.
* This is a required step for modules wishing to display their own pages,
* because the process of creating the links also tells Drupal what
* callback function to use for a given URL. The menu items returned
* here provide this information to the menu system.
*
* With the below menu definitions, URLs will be interpreted as follows:
*
* If the user accesses http://example.com/?q=foo, then the menu system
* will first look for a menu item with that path. In this case it will
* find a match, and execute page_example_foo().
*
* If the user accesses http://example.com/?q=bar, no match will be found,
* and a 404 page will be displayed.
*
* If the user accesses http://example.com/?q=bar/baz, the menu system
* will find a match and execute page_example_baz().
*
* If the user accesses http://example.com/?q=bar/baz/1/2, the menu system
* will first look for bar/baz/1/2. Not finding a match, it will look for
* bar/baz/1. Again not finding a match, it will look for bar/baz. This
* time it finds a match, and so will execute page_example_baz(1,2). Note
* the parameters being passed; this is a very useful technique.
*
* If the user accesses http://example.com/?q=bar/baz/52/97, the menu system
* finds a match, but since its callback is absent, it proceeds
* as above and ends up calling page_example_baz(52,97) nonetheless.
*/
function page_example_menu($may_cache) {
$items = array();
// The $may_cache parameter is used to divide menu items into two parts. Those
// returned when $may_cache is true must be consistently applicable for the
// current user at all times; the others may change or be defined at only
// certain paths. Most modules will have excusively cacheable menu items.
if ($may_cache) {
// This is the minimum information you can provide for a menu item.
$items[] = array(
'path' => 'foo',
'title' => t('foo'),
'callback' => 'page_example_foo',
'access' => user_access('access foo'),
);
// By using the MENU_CALLBACK type, we can register the callback for this
// path but not have the item show up in the menu; the admin is not allowed
// to enable the item in the menu, either.
$items[] = array(
'path' => 'bar/baz',
'title' => t('baz'),
'callback' => 'page_example_baz',
'access' => user_access('access baz'),
'type' => MENU_CALLBACK,
);
// Here is a menu item that doesn't register a callback. By default, the
// attributes are inherited from the parent menu item. In this case, the
// permissions of the parent suffice but we to override the title if
// they enter some "magic" parameters. Note: if you remove the 'type'
// attribute, the item will appear in the menu.
$items[] = array(
'path' => 'bar/baz/52/97',
'title' => t('the magic numbers'),
'type' => MENU_CALLBACK,
);
}
return $items;
}
/**
* A simple page callback.
*
* Page callbacks are required to return the entire page. The content
* is then usually output via a call to theme('page'), where the theme system
* will then surround the content in the appropriate blocks, navigation, and
* styling.
*
* If you do not want to use the theme system (for example for outputting an
* image or XML), you should print the content yourself and not return anything.
*/
function page_example_foo() {
$content = '<p>The quick brown fox jumps over the lazy dog.</p>';
return $content;
}
/**
* A more complex page callback that takes arguments.
*
* The arguments are passed in from the page URL. They are always the next
* elements of the path after the page location. Because of this, if the
* URL of the page is moved later, this function does not need to be changed
* to accomodate the move. It's a good idea to always provide default values
* for the parameters
*/
function page_example_baz($alice = 0, $bob = 0) {
// Make sure you don't trust the URL to be safe! Always check for exploits.
if (!is_numeric($alice) || !is_numeric($bob)) {
// We will just show a standard "access denied" page in this case.
drupal_access_denied();
return;
}
$list[] = "Alice's number was {$alice}.";
$list[] = "Bob's number was {$bob}.";
$list[] = 'The total was ' . ($alice + $bob) . '.';
$content = theme('item_list', $list);
return $content;
}
Functions
Name | Description |
---|---|
page_example_baz | A more complex page callback that takes arguments. |
page_example_foo | A simple page callback. |
page_example_help | Implementation of hook_help(). |
page_example_menu | Implementation of hook_menu(). |
page_example_perm | Implementation of hook_perm(). |