This document provides an overview of routing in Drupal 8. It explains that routing replaces hook_menu() from Drupal 7 and uses route files to define paths and callbacks. Paths can map to multiple routes and dynamic placeholders are supported. Forms are classes that implement interfaces rather than functions. Access, local tasks, actions and contextual links are also defined through route files rather than hook_menu.

1. Routing in Drupal 8
November 13, 2014

2. Nice to Meet You!
Kalpana Goel
Developer
Drupal.org - kgoel
Twitter - @kalpanagoel
William Hurley
Manager, Technical
Development

3. What is a route?
Routes are the mappings between URL paths and
their corresponding page and access callbacks.

4. What’s Changed

5. hook_menu defines the
routing in Drupal 7
1:1 mapping of path to route

6. hook_menu is dead in 8.0.x
There is no hook_menu in Drupal 8!
MODULENAME.routing.yml
One path may map to multiple routes

8. Why the Change?

9. D7 hook_menu
● Routing (page and access callbacks)
● Menu links
● Local actions
● Local tasks
● Breadcrumbs
● Contextual links
● Title
● Weight

10. *.links.actin.ml *.links.contexual.yml

11. Basic Example

12. D7: hook_menu()
function user_menu() {
$items['user/logout'] = array(
'title' => 'Log out',
'access callback' => 'user_is_logged_in',
'page callback' => 'user_logout',
'weight' => 10,
'menu_name' => 'user-menu',
'file' => 'user.pages.inc',
);
return $items;
}

13. D7: page callback
/**
* Menu callback; logs the current user out, and redirects to the home page.
*/
function user_logout() {
global $user;
watchdog('user', 'Session closed for %name.', array('%name' => $user->name));
module_invoke_all('user_logout', $user);
// Destroy the current session, and reset $user to the anonymous user.
session_destroy();
drupal_goto();
}

14. D8: Routing
user.routing.yml
user.logout:
path: '/user/logout'
defaults:
_controller: 'DrupaluserControllerUserController::logout'
requirements:
_user_is_logged_in: 'TRUE'

15. D8: Controller
namespace DrupaluserController;
class UserController extends ControllerBase {
public function logout() {
user_logout();
return $this->redirect('<front>');
}

16. Path Variables

17. D8: Path (required)
For dynamic properties, you can include them in curly braces.
For example -
‘/admin/structure/views/{js}/display/{view}/{display_id}/{type}'
The {display_id} element in the URL is called a placeholder and
is available as $display_id in the controller method.

18. D8: dynamic path example
views_ui.form_display:
path: '/admin/structure/views/{js}/display/{view}/{display_id}/{type}'
defaults:
_content: 'Drupalviews_uiFormAjaxDisplay::getForm'
class Display extends ViewsFormBase {
public function getForm(ViewStorageInterface $view, $display_id, $js, $type =
NULL) {
$this->setType($type);
return parent::getForm($view, $display_id, $js);
}

19. D8: Optional Attributes
user.cancel_confirm:
path: '/user/{user}/cancel/confirm/{timestamp}/{hashed_pass}'
defaults:
_title: 'Confirm account cancellation'
_content: 'DrupaluserControllerUserController::confirmCancel'
timestamp: 0
hashed_pass: ''

20. D8: Page Title
user.view:
path: '/user/{user}'
defaults:
_entity_view: 'user.full'
_title_callback: 'DrupaluserControllerUserController::userTitle'
requirements:
_entity_access: 'user.view'

21. D8: Page Types
_content : - display content on a page
_form : - display form on a page.
_controller : - use to generate raw data like json output
_entity_view : - for example - node.teaser
_entity_form : - display a form for a entity
_entity_list : - display list of entity like node

22. Access Restrictions

23. D8: Access checking
user.admin_account:
path: '/admin/people'
defaults:
_entity_list: 'user'
_title: 'People'
requirements:
_permission: 'administer users'

24. D8: Access checkers
Based upon roles, permissions:
_permission - A permission string (e.g. - _permission: ‘access
content’)
_role : A specific user role (e.g.- administrator)

25. D8: Access checkers
Based upon access to Entities (view, update, delete)
_entity_access: In case where an entity is part of route, can check
a certain access level before granting access (e.g. node.view)
Example:
_entity_access: node.view

26. D8: Access check
Custom Access
_custom_access: You can also do custom access checking on
route.
Same as title callback (define as method on class)Read more -
https://www.drupal.org/node/2122195
_custom_access: DrupalshortcutFormSwitchShortcutSet::checkAccess
public function checkAccess(UserInterface $user = NULL) {
return shortcut_set_switch_access($user);
}

27. D8: Access check
Access check for everyone
grant access to everyone
_access: TRUE

28. D8: Access check
Multiple access check -
node.add_page:
path: '/node/add'
defaults:
_title: 'Add content'
_content:
'DrupalnodeControllerNodeController::addPage'
options:
_access_mode: 'ANY'
_node_operation_route: TRUE
requirements:
_permission: 'administer content types'
_node_add_access: 'node'

29. Forms

30. D7: Form Router
$items['user/password'] = array(
'title' => 'Request new password',
'page callback' => 'drupal_get_form',
'page arguments' => array('user_pass'),
'access callback' => TRUE,
'type' => MENU_LOCAL_TASK,
'file' => 'user.pages.inc',
);

31. D7: User Password Form
function user_pass() {
$form['name'] = array(
'#type' => 'textfield',
'#title' => t('Username or e-mail address'),
'#size' => 60,
'#maxlength' => max(USERNAME_MAX_LENGTH,
EMAIL_MAX_LENGTH),
'#required' => TRUE,
'#default_value' => isset($_GET['name']) ? $_GET['name'] : '',
);
[...]
}
function user_pass_validate($form, &$form_state)
function user_pass_submit($form, &$form_state)

32. D8: Form Router
Forms are classes
There is no method in forms as forms are presented as one class
Use _form instead of _content or _controller
user.pass:
path: '/user/password'
defaults:
_form: 'DrupaluserFormUserPasswordForm'
_title: 'Request new password'
requirements:
_access: 'TRUE'
options:
_maintenance_access: TRUE

33. D8: Form Interface
namespace DrupalCoreForm;
interface FormInterface {
public function getFormId() {
return 'user_pass';
}

34. D8: Form Interface
public function buildForm(array $form, FormStateInterface $form_state) {
$form['name'] = array(
'#type' => 'textfield',
'#title' => $this->t('Username or email address'),
'#size' => 60,
'#maxlength' => max(USERNAME_MAX_LENGTH,
Email::EMAIL_MAX_LENGTH),
'#required' => TRUE,
'#attributes' => array(
'autocorrect' => 'off',
'autocapitalize' => 'off',
'spellcheck' => 'false',
'autofocus' => 'autofocus',
),
);

35. pubDlic8 fu:n Fctioonr mvali dIantetFeorrmfa(acrreay &$form, FormStateInterface $form_state) {
$name = trim($form_state->getValue('name'));
$users = $this->userStorage->loadByProperties(array('mail' => $name, 'status' =>
'1'));
if (empty($users)) {
$users = $this->userStorage->loadByProperties(array('name' => $name, 'status'
=> '1'));
}
if ($account && $account->id()) {
$form_state->setValueForElement(array('#parents' => array('account')),
$account);
}
else {
$form_state->setErrorByName('name', $this->t('Sorry, %name is not recognized
as a username or an email address.', array('%name' => $name)));
$account = reset($users);
}

36. public function submitForm(array &$form, FormStateInterface $form_state) {
$langcode = $this->languageManager->getCurrentLanguage()->getId();
$account = $form_state->getValue('account');
// Mail one time login URL and instructions using current language.
$mail = _user_mail_notify('password_reset', $account, $langcode);
if (!empty($mail)) {
$this->logger('user')->notice('Password reset instructions mailed to %name
at %email.', array('%name' => $account->getUsername(), '%email' =>
$account->getEmail()));
drupal_set_message($this->t('Further instructions have been sent to your
email address.'));
}
$form_state->setRedirect('user.page');
}

37. D8: Form Base class
** generic base class - this includes string translation, link generator
DrupalCoreFormFormBase
for example -
class UserLoginForm extends FormBase
* * Base class for implementing system configuration forms.
DrupalcoreformConfigFormBase
for example -
class MenuSettingsForm extends ConfigFormBase
** base class for a confirmation form.
DrupalCoreFormConfirmFormBase
for example -
class UserMultipleCancelConfirm extends ConfirmFormBase

38. Other functionality
from hook_menu

39. local task

40. local task

41. local task

42. D7: menu local tasks
$items['user/password'] = array(
'title' => 'Request new password',
'page callback' => 'drupal_get_form',
'page arguments' => array('user_pass'),
'access callback' => TRUE,
'type' => MENU_LOCAL_TASK,
'file' => 'user.pages.inc',
);

43. D8: menu local tasks
user.links.task.yml
user.page:
route_name: user.page
base_route: user.page
title: 'Log in'
weight: -10
user.pass:
route_name: user.pass
base_route: user.page
title: 'Request new password'

44. local action

45. D7: Local action
$items['admin/structure/types/add'] = array(
'title' => 'Add content type',
'page callback' => 'drupal_get_form',
'page arguments' => array('node_type_form'),
'access arguments' => array('administer content types'),
'type' => MENU_LOCAL_ACTION,
'file' => 'content_types.inc',
);

46. D8: Local action
node.links.action.yml
node.add_page:
route_name: node.add_page
title: 'Add content'
appears_on:
- system.admin_content

47. D8: Local action on multiple pages
block_content.links.action.yml
block_content_add_action:
route_name: block_content.add_page
title: 'Add custom block'
class:
Drupalblock_contentPluginMenuLocalActionBlockContentAddLocalAction
appears_on:
- block.admin_display
- block.admin_display_theme
- block_content.list

48. D8: Contextual
links

49. D7: Contextual
links $items['admin/structure/block/manage/%/%/configure'] = array(
'title' => 'Configure block',
'type' => MENU_DEFAULT_LOCAL_TASK,
'context' => MENU_CONTEXT_INLINE,
);

50. D8: Contextual
links
block.links.contextual.yml
block_configure:
title: 'Configure block'
route_name: 'entity.block.edit_form'
group: 'block'

51. D8: Path based breadcrumb
breadcrumb is path based in Drupal 8
/node/add/content
/node/add
/node
/
https://www.drupal.org/node/2098323

52. Useful Tips

53. Options
_admin_route -- whether to use the admin theme for this route
_maintenance_access -- whether route is publicly available when the site
is in maintenance mode
_access_mode -- whether requirements are ANY or ALL
Useful Tips

54. Useful links
https://www.drupal.org/node/1800686 - change record
https://www.drupal.org/node/2118147 - D7 to D8 upgrade tutorial
https://www.drupal.org/developing/api/8/routing - Routing system in D8

55. THANK YOU!
Kalpana Goel
William Hurley