Porting a Drupal 7 module to Drupal 8 (a real life example) #2- menu links and routing

Drupal 8’s beta version was released a few month ago and now it is time to start porting modules. To demonstrate how to do it, we’re going to use a real module called scroll_to_top, which allow us to scroll to top when we are reading an article and we want to go to the menu for example.

If you prefer watching videos, here is the screencast version of this series.

In Drupal 7, hook_menu() was probably the most implemented hook because it was used to define paths to Drupal and connect these paths with callback functions. It was also responsible for creating menu links and a bunch of other stuff, but they were replaced and in this second chapter we’re going to see how to port it.


hook_menu() conversion

For the Scroll To Top module the menu entry for configuring the module looked as such:

chunk of scroll_to_top.module

 * Implements hook_menu().
function scroll_to_top_menu() {
  $items = array();

  $items['admin/config/user-interface/scrolltotop'] = array(
    'title' => 'Scroll to top',
    'description' => 'Scroll To Top settings',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('scroll_to_top_settings'),
    'access arguments' => array('administer scroll to top'),
    'file' => 'scroll_to_top.admin.inc',
    'type' => MENU_NORMAL_ITEM,

  return $items;

Drupal 8 requires to update the routing in a dedicated routing file. So, the first thing we’re going to do is to create that file and specify the routing, this file takes the format of <module_name>.routing.yml, in our case it will be scroll_to_top.routing.yml.


  path: '/admin/config/user-interface/scrolltotop'
    _title: 'Scroll to top'
    _form: '\Drupal\scroll_to_top\Form\ScrollToTopForm'
    _permission: 'access administration pages'

The first line marks the beginning of a new route called form for the module scroll_to_top (the first is the module name and the second the route name). Under path, we specify the path we want this route to register. Under defaults, we have two things: the default page title (_title) and the _form which references a Configuration Form class. Under requirements, we specify the permission the accessing user needs to have to be able to view the page. You can consult this documentation page for more options you can have for this routing file.

Please, remember that whenever you edit or create an .yml file you have to clean all caches in order to see the changes working.

At this instance we created the routing, so if you go to http://drupalinstallation/admin/config/user-interface/scrolltotop, you will get a Drupal Error page instead a Page not found, don’t worry about the error we’re going to solve later. While you don’t get the error below everything is ok 🙂

So, to finish this chapter we need to create the menu link for our module.

  title: 'Scroll to top'
  description: 'Scroll To Top settings'
  parent: system.admin_config_ui
  route_name: scroll_to_top.form

We add a link with a title and a description in the user interface section in the Drupal configuration page (note the parent: system.admin_config_ui). When the user click on this link, it will carry it to the routing name scrolll_to_top.form (declared in scroll_to_top.routing.yml) that has configured the path admin/config/user-interface/scrolltotop. That means that when the user click on the link, it will go to the path admin/config/user-interface/scrolltotop, that is going to content our configuration form, but again, for now you are going to get an error page so don’t worry 🙂



Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s