# 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.

# Install

The only library required by this module is the
[mmenu](https://mmenujs.com) plugin. Its important to download the version
from [gitlab](https://api.github.com/repos/FrDH/mmenu-js/zipball) and place
it in your `libraries` directory, usually this is located in
`/sites/all/libraries` (create the directory if you need to). Rename your newly
placed download to mmenu, so the resulting path is `/sites/all/libraries/mmenu`.
This module will look in `/sites/all/libraries/mmenu/dist` for the javascript
files so ensure you have the correct file structure.

The other library which adds functionality (if desired) is the
[superfish](https://github.com/joeldbirch/superfish) library. Place that in
`/sites/all/libraries` and rename it to superfish. You should have a structure
like `/sites/all/libraries/superfish/dist/js`.

Note that Superfish is only compatible with jQuery versions from 1.7 onwards. To
update jQuery use the
[jquery_update](https://www.drupal.org/project/jquery_update) module.

# Upgrade from 7.x-2.x versions

When you upgrade from the 7.x-2.x version of the module you'll also need to
download and install a new version of the mmenu library (see above).

Due to class name changes upstream in the mmenu library you may need to adjust
your custom css. The main css change implemented in the provided
`responsive_menu.css` is the targeting of the `html.mm-opening` class which no
longer exists. This has changed to `.mm-wrapper_opening`. So for example:

```css
html.mm-opening .responsive-menu-toggle-icon span.icon {
```

is now:

```css
.mm-wrapper_opening .responsive-menu-toggle-icon span.icon {
```

# Configuration

As an administrator visit /admin/structure/menu/settings

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

Set your jQuery version to at least 1.7 at
/admin/config/development/jquery_update to use Superfish.

# Block placement

This modules provides two blocks. The `Responsive menu` block is an alternative
horizontal menu that can include superfish and hoverintent dropdowns. It is
optional and the off-canvas menu will work without it.

The second block is named `Responsive menu mobile icon` and should be placed
wherever you want the 'burger' style menu to be shown.

# 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.tpl.php, see [this issue](https://www.drupal.org/node/2727345)). More
details on how to set up the divs are on an [mmenu documentation
page](http://mmenu.frebsite.nl/tutorials/off-canvas/the-page.html).

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.

# Customising the mmenu config and settings (advanced, optional)

It is possible to completely customise the config provided to the mmenu library,
beyond what the module's admin form provides. This is done by way of a Drupal
hook in a custom theme or module. This hook modifies the Drupal.settings object
and provides a `custom` element for the `responsive_menu` property.

In the following example you would place this in your custom theme's `.theme`
file and change `MYTHEME` to the name of your theme. This example adds a navbar
title to the off-canvas menu with the string 'This is a test'. It also changes
the selected class name to `my-custom-menu--active-trail`:

```php
/**
 * Implements hook_js_alter().
 */
function MYTHEME_js_alter(&$javascript) {
  foreach ($javascript['settings']['data'] as &$setting) {
    if (!empty($setting['responsive_menu'])) {
      $setting['responsive_menu']['custom'] = array(
        'options' => array(
          'navbar' => array(
            'add' => TRUE,
            'title' => 'This is a test',
          ),
        ),
        'config' => array(
          'classNames' => array(
            'selected' => 'my-custom-menu--active-trail',
          ),
        ),
      );
    }
  }
}
```

# Disabling the off-canvas menu under specific conditions

In rare cases you may not want the off-canvas menu to be rendered, for example
you may have a members section of the site which uses a different menu system.
To stop the off-canvas menu from being added to the DOM and to disable the
JavaScript you can use an alter hook in your theme. Change `MYTHEME` to the
machine name of your theme:

```php
/**
 * Implements hook_page_alter().
 */
function MYTHEME_page_alter(&$page) {
  if (1 === 1) {
    $page['page_bottom']['off_canvas'] = array();
  }
}
```

You will want to change the logic in the example above to trigger only when your
specific condition has been met. This might be checking the theme name, if the
user is logged in, if the user is visiting a certain page etc.

# Licenses

The licenses for the libraries used by this module are:

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 fee to use it in a
commercial web site. Alternatively you can download the earlier MIT licensed
version which should be compatible. This module will track the latest stable
version.
