<?php
/**
* @file
* Module file for page_example_module.
*//**
* @defgroup page_example Example: Page
* @ingroup examples
* @{
* This example demonstrates how a module can display a page at a given URL.
*
* It's important to understand how the menu system works in order to
* implement your own pages. See the Menu Example module for some insight.
*
* @see menu_example
*//**
* Implements hook_help().
*
* Through hook_help(), a module can make documentation available to the user
* for the module as a whole or for specific paths. Where the help appears
* depends on the $path specified.
*
* In the first example below, the help text will appear on the simple page
* defined in hook_menu below in the region designated for help text.
*
* In the second example, the text will be available through the module page as
* a link beside the module or on the admin help page (admin/help) in the list
* of help topics using the name of the module. To specify help in the admin
* section use the module name in the path as in the second case below.
*
* @see hook_help()
*/functionpage_example_help($path, $arg) {
switch ($path) {
case'examples/page_example/simple':
// Help text for the simple page registered for this path.
returnt('This is help text for the simple page.');
case'admin/help#page_example':
// Help text for the admin section, using the module name in the path.
returnt('This is help text created in the page example\'s second case.');
}
}
/**
* Implements hook_permission().
*
* 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.
*/functionpage_example_permission() {
returnarray(
'access simple page' => array(
'title' => t('Access simple page'),
'description' => t('Allow users to access simple page'),
),
'access arguments page' => array(
'title' => t('Access page with arguments'),
'description' => t('Allow users to access page with arguments'),
),
);
}
/**
* Implements hook_menu().
*
* Because hook_menu() registers URL paths for items defined by the function, it
* is necessary for modules that create pages. Each item can also specify a
* callback function for a given URL. The menu items returned here provide this
* information to the menu system.
*
* We will define some menus, and their paths will be interpreted as follows:
*
* If the user accesses http://example.com/?q=examples/page_example/simple,
* 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_simple().
*
* If the user accesses http://example.com/?q=examples/page_example/arguments,
* the menu system will find no explicit match, and will fall back to the
* closest match, 'examples/page_example', executing page_example_description().
*
* If the user accesses
* http://example.com/?q=examples/page_example/arguments/1/2, the menu
* system will first look for examples/page_example/arguments/1/2. Not finding
* a match, it will look for examples/page_example/arguments/1/%. Again not
* finding a match, it will look for examples/page_example/arguments/%/2.
* Yet again not finding a match, it will look for
* examples/page_example/arguments/%/%. This time it finds a match, and so will
* execute page_example_arguments(1, 2). Since the parameters are passed to
* the function after the match, the function can do additional checking or
* make use of them before executing the callback function.
*
* @see hook_menu()
* @see menu_example
*/functionpage_example_menu() {
// This is the minimum information you can provide for a menu item. This menu
// item will be created in the default menu, usually Navigation.
$items['examples/page_example'] = array(
'title' => 'Page Example',
'page callback' => 'page_example_description',
'access callback' => TRUE,
'expanded' => TRUE,
);
$items['examples/page_example/simple'] = array(
'title' => 'Simple - no arguments',
'page callback' => 'page_example_simple',
'access arguments' => array('access simple page'),
);
// By using the MENU_CALLBACK type, we can register the callback for this
// path without the item appearing in the menu; the admin cannot enable the
// item in the menu, either.
//
// Notice that 'page arguments' is an array of numbers. These will be
// replaced with the corresponding parts of the menu path. In this case a 0
// would be replaced by 'example', a 1 by 'page_example', and a 2 by
// 'arguments.' 3 and 4 will be replaced by whatever the user provides.
// These will be passed as arguments to the page_example_arguments() function.
$items['examples/page_example/arguments/%/%'] = array(
'page callback' => 'page_example_arguments',
'page arguments' => array(3, 4),
'access arguments' => array('access arguments page'),
'type' => MENU_CALLBACK,
);
return$items;
}
/**
* Constructs a descriptive page.
*
* Our menu maps this function to the path 'examples/page_example'.
*
*/functionpage_example_description() {
returnarray('#markup' => t('The page_example provides two pages, "simple" and "arguments". The <a href="@simple_link">simple page</a> just returns a renderable array for display. The <a href="@arguments_link">arguments page</a> takes two arguments and displays them, as in @arguments_link', array('@simple_link' => url('examples/page_example/simple', array('absolute' => TRUE)), '@arguments_link' => url('examples/page_example/arguments/23/56', array('absolute' => TRUE)))));
}
/**
* Constructs a simple page.
*
* The simple page callback, mapped to the path 'examples/page_example/simple'.
*
* Page callbacks return a renderable array with the content area of the page.
* The theme system will later render and 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.
*/functionpage_example_simple() {
returnarray('#markup' => '<p>' . t('Simple page: The quick brown fox jumps over the lazy dog.') . '</p>');
}
/**
* A more complex page callback that takes arguments.
*
* This callback is mapped to the path 'examples/page_example/arguments/%/%'.
*
* The % arguments are passed in from the page URL. In our hook_menu
* implementation we instructed the menu system to extract the last two
* parameters of the path and pass them to this function as arguments.
*
* This function also demonstrates a more complex render array in the returned
* values. Instead of just rendering the HTML with a theme('item_list'), the
* list is left unrendered, and a #theme attached to it so that it can be
* rendered as late as possible, giving more parts of the system a chance to
* change it if necessary.
*
* Consult @link http://drupal.org/node/930760 Render Arrays documentation
* @endlink for details.
*/functionpage_example_arguments($first, $second) {
// Make sure you don't trust the URL to be safe! Always check for exploits.
if (!is_numeric($first) || !is_numeric($second)) {
// We will just show a standard "access denied" page in this case.
drupal_access_denied();
return; // We actually don't get here.
}
$list[] = t("First number was @number.", array('@number' => $first));
$list[] = t("Second number was @number.", array('@number' => $second));
$list[] = t('The total was @number.', array('@number' => $first + $second));
$render_array['page_example_arguments'] = array(
'#theme' => 'item_list', // The theme function to apply to the #items
'#items' => $list, // The list itself.
'#title' => t('Argument Information'),
);
return$render_array;
}
/**
* @} End of "defgroup page_example".
*/