1. 4.6.x developer/examples/page_example.module
  2. 4.7.x developer/examples/page_example.module
  3. 5.x developer/examples/page_example.module

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.module
View 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. We don't need the
    // "access" attribute either in this case, since the permissions of the
    // parent menu item suffice.
    $items[] = array(
      'path' => 'bar/baz/52/97',
      'title' => t('adding game'),
    );
  }
  return $items;
}

/**
 * A simple page callback.
 *
 * Page callbacks are required to print the entire page. This is usually
 * accomplished via a call to theme('page'), passing the page content as
 * a parameter. The theme system will then surround the content in the
 * appropriate blocks, navigation, and styling.
 */
function page_example_foo() {
  $content = '<p>The quick brown fox jumps over the lazy dog.</p>';
  print theme('page', $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.
 */
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);
  print theme('page', $content);
}

Functions

Namesort descending 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().