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
  1. <?php
  2. /**
  3. * @file
  4. * This is an example outlining how a module can be used to display a
  5. * custom page at a given URL.
  6. */
  7. /**
  8. * Implementation of hook_help().
  9. *
  10. * Throughout Drupal, hook_help() is used to display help text at the top of
  11. * pages. Some other parts of Drupal pages get explanatory text from these hooks
  12. * as well. We use it here to illustrate how to add help text to the pages your
  13. * module defines.
  14. */
  15. function page_example_help($section) {
  16. switch ($section) {
  17. case 'foo':
  18. // Here is some help text for a custom page.
  19. return t('This sentence contains all the letters in the English alphabet.');
  20. }
  21. }
  22. /**
  23. * Implementation of hook_perm().
  24. *
  25. * Since the access to our new custom pages will be granted based on
  26. * special permissions, we need to define what those permissions are here.
  27. * This ensures that they are available to enable on the user role
  28. * administration pages.
  29. */
  30. function page_example_perm() {
  31. return array('access foo', 'access baz');
  32. }
  33. /**
  34. * Implementation of hook_menu().
  35. *
  36. * You must implement hook_menu() to emit items to place in the main menu.
  37. * This is a required step for modules wishing to display their own pages,
  38. * because the process of creating the links also tells Drupal what
  39. * callback function to use for a given URL. The menu items returned
  40. * here provide this information to the menu system.
  41. *
  42. * With the below menu definitions, URLs will be interpreted as follows:
  43. *
  44. * If the user accesses http://example.com/?q=foo, then the menu system
  45. * will first look for a menu item with that path. In this case it will
  46. * find a match, and execute page_example_foo().
  47. *
  48. * If the user accesses http://example.com/?q=bar, no match will be found,
  49. * and a 404 page will be displayed.
  50. *
  51. * If the user accesses http://example.com/?q=bar/baz, the menu system
  52. * will find a match and execute page_example_baz().
  53. *
  54. * If the user accesses http://example.com/?q=bar/baz/1/2, the menu system
  55. * will first look for bar/baz/1/2. Not finding a match, it will look for
  56. * bar/baz/1. Again not finding a match, it will look for bar/baz. This
  57. * time it finds a match, and so will execute page_example_baz(1,2). Note
  58. * the parameters being passed; this is a very useful technique.
  59. *
  60. * If the user accesses http://example.com/?q=bar/baz/52/97, the menu system
  61. * finds a match, but since its callback is absent, it proceeds
  62. * as above and ends up calling page_example_baz(52,97) nonetheless.
  63. */
  64. function page_example_menu($may_cache) {
  65. $items = array();
  66. // The $may_cache parameter is used to divide menu items into two parts. Those
  67. // returned when $may_cache is true must be consistently applicable for the
  68. // current user at all times; the others may change or be defined at only
  69. // certain paths. Most modules will have excusively cacheable menu items.
  70. if ($may_cache) {
  71. // This is the minimum information you can provide for a menu item.
  72. $items[] = array('path' => 'foo', 'title' => t('foo'),
  73. 'callback' => 'page_example_foo',
  74. 'access' => user_access('access foo'));
  75. // By using the MENU_CALLBACK type, we can register the callback for this
  76. // path but not have the item show up in the menu; the admin is not allowed
  77. // to enable the item in the menu, either.
  78. $items[] = array('path' => 'bar/baz', 'title' => t('baz'),
  79. 'callback' => 'page_example_baz',
  80. 'access' => user_access('access baz'),
  81. 'type' => MENU_CALLBACK);
  82. // Here is a menu item that doesn't register a callback. By default, the
  83. // attributes are inherited from the parent menu item. In this case, the
  84. // permissions of the parent suffice but we to override the title if
  85. // they enter some "magic" parameters. Note: if you remove the 'type'
  86. // attribute, the item will appear in the menu.
  87. $items[] = array('path' => 'bar/baz/52/97',
  88. 'title' => t('the magic numbers'),
  89. 'type' => MENU_CALLBACK);
  90. }
  91. return $items;
  92. }
  93. /**
  94. * A simple page callback.
  95. *
  96. * Page callbacks are required to return the entire page. The content
  97. * is then usually output via a call to theme('page'), where the theme system
  98. * will then surround the content in the appropriate blocks, navigation, and
  99. * styling.
  100. *
  101. * If you do not want to use the theme system (for example for outputting an
  102. * image or XML), you should print the content yourself and not return anything.
  103. */
  104. function page_example_foo() {
  105. $content = '<p>The quick brown fox jumps over the lazy dog.</p>';
  106. return $content;
  107. }
  108. /**
  109. * A more complex page callback that takes arguments.
  110. *
  111. * The arguments are passed in from the page URL. They are always the next
  112. * elements of the path after the page location. Because of this, if the
  113. * URL of the page is moved later, this function does not need to be changed
  114. * to accomodate the move. It's a good idea to always provide default values
  115. * for the parameters
  116. */
  117. function page_example_baz($alice = 0, $bob = 0) {
  118. // Make sure you don't trust the URL to be safe! Always check for exploits.
  119. if (!is_numeric($alice) || !is_numeric($bob)) {
  120. // We will just show a standard "access denied" page in this case.
  121. drupal_access_denied();
  122. return;
  123. }
  124. $list[] = "Alice's number was $alice.";
  125. $list[] = "Bob's number was $bob.";
  126. $list[] = 'The total was '. ($alice + $bob) .'.';
  127. $content = theme('item_list', $list);
  128. return $content;
  129. }

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