Create a custom page

Last updated on
24 January 2017

There are two steps in creating a simple page in Drupal:

Declare the path and its options.

This step includes the page title, the access requirements for the page, and others.

In Drupal 7, you had to implement hook_menu().

In Drupal 8, create the file <module_name>.routing.yml in the top-level module directory.

Write code to return the page body.

In Drupal 7, you had to write the page-callback function specified in hook_menu().

In Drupal 8, the page callback must be either a class method or a registered service. It can be different depending on various conditions (HTTP vs. HTTPS, content headers, others) but that is beyond the scope of this introduction.


Following the example on this page, you should be able to create a simple page in your custom module, without having to learn more about Drupal's internals. For more details, see the change record for changing the routing system and the various implementations in core and the examples project.

Routing YAML file for the Example module

The routing information is stored in example/example.routing.yml:

  path: '/mypage/page'
    _controller: '\Drupal\example\Controller\ExampleController::myPage'
    _title: 'My first page in D8'
    _permission: 'access content'
This is the machine name of the route. By convention, route machine names should be module_name.sub_name. When other parts of the code need to refer to the route, they will use the machine name.
This gives the path to the page on your site. Note the leading slash (/)!
This describes the page and title callbacks. @todo: Where can these defaults be overridden?
This specifies the conditions under which the page will be displayed. You can specify permissions, modules that must be enabled, and other conditions.

Page implementation for the Example module

The Controller class ExampleController should be defined in example/src/Controller/ExampleController.php:

namespace Drupal\example\Controller;

use Drupal\Core\Controller\ControllerBase;

 * Provides route responses for the Example module.
class ExampleController extends ControllerBase {

   * Returns a simple page.
   * @return array
   *   A simple renderable array.
  public function myPage() {
    $element = array(
      '#markup' => 'Hello, world',
    return $element;

This declares the prefix needed to fully qualify the name of the class we are defining. Compare the file's doc block and the name of the class. The class auto-loader knows that, to find the class \Drupal\example\Controller\ExampleController, it should look for the file modules/example/src/Controller/ExampleController.php.
This allows us to use ControllerBase instead of the fully qualified name. This makes our class line much easier to read.
The method specified in the YAML file must be public. It should return a renderable array.