Drupal 8 module development #2 - adding basic routing

This is the 2nd of several on-going blog post series which aim to educate on the process of porting modules to Drupal 8 with real life examples by porting a popular Drupal 7 module to Drupal 8.

In the previous article we looked into the very basic job of beginning a module's port to Drupal 8 and that was to update the module .info file. Next up, we will take a look at updating the routing system create a valid menu entry which will point to the module's settings page.

In Drupal 7 and previous versions, it was required to implement hook_menu() and return an associative array with a list of parameters which define the menu entry, such as the routing path, the title, access permissions etc. For the Global Redirect module that menu entry for configuring the module looked as such:

 

/**
 * Implements hook_menu().
 */
function globalredirect_menu() {
  $items['admin/config/system/globalredirect'] = array(
    'title' => 'Global Redirect',
    'description' => 'Choose which features you would like enabled for Global Redirect',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('globalredirect_settings'),
    'access arguments' => array('administer site configuration'),
    'file' => 'globalredirect.admin.inc',
  );

  return $items;
}

With Drupal 8, it is required to update the routing in a dedicated routing file, as well as implementing hook_menu(), so the first order of business would be to create the routing file which takes the format of <module_name>.routing.yml, in our case it will be globalredirect.routing.yml, and we will add the routing information to it:

globalredirect_settings:
  path: '/admin/config/system/globalredirect'
  defaults:
    _form: 'Drupal\globalredirect\Form\GlobalredirectSettingsForm'
  requirements:
    _permission: 'administer site configuration'

The routing declaration begins by specifying the name of this route entry globalredirect_settings, followed by the settings for it. The pattern is used to identify the URL pattern and can actually contain named placeholder parameters like we've seen in previous hook_menu() implementations (although they take a different syntax here). The next _form entry specifies the form class which Drupal expects to load for the settings form, and finally the _permission entry specifies the access control to validate the user has specific access.

Followed by routing file, we'll update the hook_menu() implementation to correlate with the routing entry:

/**
 * Implements hook_menu().
 */
function globalredirect_menu() {
  $items = array();
  $items['globalredirect_settings'] = array(
    'title' => 'Global Redirect',
    'description' => 'Choose which features you would like enabled for Global Redirect.',
    'route_name' => 'globalredirect_settings',
  );
  return $items;
}

As you can see hook_menu() implementation is quite simpler now. While we used the route name for the routing entry in the $items array, it's not a must and we could've specified the path just as well. It's the route_name array key which actually matters.

Comments

5

Sadly, none of this appears to be in the hook_menu() API documentation yet:
https://api.drupal.org/api/drupal/core!modules!system!system.api.php/fun...
 

is it just me, or looking at this example it looks like Drupal became just an overhead for Symphony? Why do you need to define route in two places?

Taken from https://groups.drupal.org/node/313408 :

"All form and page callbacks are being converted to the new routing system. The procedural versions of these callbacks will be removed from the core codebase, and before Drupal 8.0 is released, hook_menu() will no longer work to register callbacks."

So things are still going to change...

Thanks for the posts. Just wanted to point out that "pattern" is now "path" in *.routing.yml files: https://drupal.org/node/2089727

thanks, I updated it :)

Add new comment

Filtered HTML

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.