Responsive menu module 8.x-2.x version instructions

About

This module integrates the mmenu jquery plugin with Drupal's menu system with the aim of having an off-canvas mobile menu and a horizontal menu at wider widths. It integrates with your theme's breakpoints to allow you to trigger the display of the horizontal menu at your desired breakpoint. The mobile off-canvas menu is displayed through a toggle icon or with the optional integration of swipe gestures.

Compatibility

This module currently supports the 7.x.x version of the mmenu library. See this issue for updates on the latest 8.x.x version.

Responsive Menu module versions from 8.x-2.5 are not compatible with Drupal 8.3.x or earlier. If you are running Drupal 8.4.x or later you need to update to 8.x-2.5 or later of this module.

Responsive Menu module version 8.x-2.5 introduced version checking for specific 3rd party libraries required by the module. The mmenu library must be between version 6.1.x to 7.x.x for module versions from 8.x-2.5. If you want to an earlier version of this module then you need to use mmenu 5.x.x.

You can check compatibility with your libraries on the status page: /admin/reports/status

Install

Bower method:

If you have bower installed you can change directory into the responsive_menu module directory and run bower install. This will create a libraries directory which you must move to your Drupal root.

Manual method:

The only library required by this module is the mmenu plugin. You need to download version 7.3.3, rename it to mmenu and place it in /libraries in your docroot. This will result in a folder structure like /libraries/mmenu

This module will look in /libraries/mmenu/dist/ for the javascript and and the css, so ensure you have the correct file structure.

The other two libraries which add functionality (if desired) are the superfish plugin and the hammerjs library. Place those in /libraries and rename them to superfish and hammerjs. For superfish you should have a structure like /libraries/superfish/dist/js, while hammerjs should be simply /libraries/hammerjs.

Download links for the current versions of each of these libraries are:

• mmenu: https://github.com/FrDH/mmenu-js/archive/v7.3.3.zip
• superfish: https://api.github.com/repos/joeldbirch/superfish/zipball
• hammerjs: https://api.github.com/repos/hammerjs/hammer.js/zipball

Note: Please do not download mmenu from http://mmenu.frebsite.nl as that version has a different file layout and is incompatible with this module.

Configuration

As an administrator visit /admin/config/user-interface/responsive-menu

You can set the various options. Some of the options will require the libraries to be present before allowing configuration.

Block placement

The module provides two blocks, one for the horizontal menu, labeled in the block UI as "Horizontal menu". The other is labeled as "Responsive menu mobile icon" and is the 'burger' menu icon and text which allows the user to toggle the mobile menu open and closed. Both blocks should be placed in an appropriate region, like the header region. The horizontal menu is designed to replace any existing main menu block you might already have in your theme.

Theming and theme compatibility

This module should be compatible with most themes. One basic requirement is that the theme includes a wrapping 'page' div. This is so that mmenu knows which elements belong inside the wrapper when the off canvas menu is opened. Bartik is an example of a theme with a wrapping div. Bootstrap (3) is an example of a theme which doesn't have the wrapping div (although you can easily add one to page.html.twig, see this issue, in particular comment #7). More details on how to set up the divs are on an mmenu documentation page.

It should also be noted that the default css that comes with the module provides some very basic styling and should be copied and pasted into your theme's css so that you can modify it to fit your theme's style. Once you've copied and pasted the css into your stylesheet you can disable the inclusion of the module's css on the settings page.

Licenses

The licenses for the libraries used by this module are:

hammerjs: MIT
mmenu: Creative Commons Attribution-NonCommercial
superfish: MIT

The mmenu plugin used to have an MIT license but has changed to the CC NonCommercial license. So you'll need to pay the developer a (small) fee to use it in a commercial web site.

Multilingual sites

Multilingual sites can use the module as follows:

• Defines separate Drupal menus for each language of the site. The example below assumes that the menu called 'main' is the main navigation for Finnish and a separate menu called 'main-en' is the main navigation for English language version.
• This module provides two blocks: the horizontal menu and the off-canvas mobile menu. The menu / menus that are shown in these blocks can be configured in the module settings at /admin/config/user-interface/responsive-menu. Define the menu / menus of your primary language here.
• This module provides API hooks so that other modules can alter the menus that are displayed in the horizontal / off-canvas blocks provided by this module. You can swap the menus based on the current language in these alter hooks, see example implementations below.

Example hook implementations / MYMODULE.module

<?php

/**
 * Alter the menu names used by the off-canvas responsive menu.
 *
 * Changes the source menu based on the language. The menu defined in module
 * settings is 'main' which is the Finnish main menu. Swap the menu to 'main-en'
 * if the current language is 'en'.
 *
 * @param string $menus
 *   Contains the machine names of all menus, separated by commas, to be
 *   concatenated into a single menu structure for the off-canvas menu.
 */
function MYMODULE_responsive_menu_off_canvas_menu_names_alter(&$menus) {
  $language = \Drupal::languageManager()->getCurrentLanguage()->getId();
  if ($language == 'en') {
    $menus = 'main-en';
  }
}

/**
 * Alter the menu name used by the horizontal responsive menu.
 *
 * Changes the source menu based on the language. The menu defined in module
 * settings is 'main' which is the Finnish main menu. Swap the menu to 'main-en'
 * if the current language is 'en'.
 *
 * @param string $menu_name
 *   The machine name of the menu configured for the horizontal menu.
 */
function MYMODULE_responsive_menu_horizontal_menu_name_alter(&$menu_name) {
  $language = \Drupal::languageManager()->getCurrentLanguage()->getId();
  if ($language == 'en') {
    $menu_name = 'main-en';
  }
}

The module also provides API hooks for altering the menu tree content, see responsive_menu.api.php for details.