Custom build introduction

The mmenu.js plugin uses Gulp as a taskrunner. It compiles, minifies and concatenates the .css and .js files. With Gulp, it is really easy to create a customized version of the plugin in just a few steps.

If you're not familiar with using the command line, have a look at this great tutorial.

Setup the directory and files

First, lets create a new directory where we'll put our customized input and output files. In favor of updating your package later on, it is advised this new directory is outside of the plugin package directory.

For the examples on this page, we'll assume the new directory is called custom-build/src and is located in the same directory as the plugin package directory.

If you'd like to use the command line, navigate to the plugin package directory and run these commands.

$ cd /path/to/project/mmenu-js
$ mkdir ../custom-build
$ mkdir ../custom-build/src

Now we need to copy the src/mmenu.js and src/mmenu.scss files from the plugin package directory to the custom-build/src directory.

If you'd like to use the command line, navigate to the plugin package directory and run these commands.

$ cd /path/to/project/mmenu-js
$ cp src/mmenu.js ../custom-build/src
$ cp src/mmenu.css ../custom-build/src

You now have a directory that looks something like this.

project
 |- custom-build
 |  |- src
 |     |- mmenu.scss
 |     |- mmenu.js
 |- mmenu-js
    |- ...
    |- dist
    |- ...
    |- src
    |- ...

Customize the JS file

Open the custom-build/src/mmenu.js file in an editor and remove (or comment out) the add-ons and framework wrappers you do not need, you should remove (or comment out) both the import line and the line where it is added to the plugin. Note that the core add-ons are highly recommended for a stable, bugfree and accessible menu.

Do NOT remove (or comment out) the import line for the core (Mmenu). Without it, nothing works at all.

Next, change the remaining import paths so they point to the modules in the dist directory in the plugin package directory. Note that an import path should always start with ./ or ../

If you're not using the jQuery/Zepto plugin, you could also remove (or comment out) the last part of the file (everything below // jQuery plugin).

Your custom-build/src/mmenu.js file now looks something like this.

//  Core
import Mmenu        from "../../mmenu-js/dist/core/oncanvas/mmenu.oncanvas";

//  Core add-ons
import offcanvas    from "../../mmenu-js/dist/core/offcanvas/mmenu.offcanvas";
import screenReader from "../../mmenu-js/dist/core/screenreader/mmenu.screenreader";
import scrollBugFix from "../../mmenu-js/dist/core/scrollbugfix/mmenu.scrollbugfix";

//  Add-ons
import counters     from "../../mmenu-js/dist/addons/counters/mmenu.counters";
import navbars      from "../../mmenu-js/dist/addons/navbars/mmenu.navbars";

//  Wrappers
import bootstrap    from "../../mmenu-js/dist/wrappers/bootstrap/mmenu.bootstrap";

Mmenu.addons = {
    //  Core add-ons
    offcanvas,
    screenReader,
    scrollBugFix,

    //  Add-ons
    counters,
    navbars
};

//  Wrappers
Mmenu.wrappers = {
   bootstrap
};

//   Global namespace
window.Mmenu = Mmenu

Customize the CSS file

Open the custom-build/src/mmenu.scss file in an editor and remove (or comment out) the @import lines for the add-ons, extensions and framework wrappers you do not need. Note that the core add-ons are highly recommended for a stable, bugfree and accessible menu.

Do NOT remove (or comment out) the @import line for the core (core/oncanvas/mmenu.oncanvas). Without it, nothing works at all.

Next, change the remaining @import paths so they point to the files in the src directory in the plugin package directory.

Your custom-build/src/mmenu.scss file now looks something like this.

//   Core
@import "../../mmenu-js/src/core/oncanvas/mmenu.oncanvas";

//   Core add-ons
@import "../../mmenu-js/src/core/offcanvas/mmenu.offcanvas";
@import "../../mmenu-js/src/core/screenreader/mmenu.screenreader";

//   Add-ons
@import "../../mmenu-js/src/addons/counters/mmenu.counters";
@import "../../mmenu-js/src/addons/navbars/mmenu.navbars";

//   Extensions
@import "../../mmenu-js/src/extensions/positioning/mmenu.positioning";
@import "../../mmenu-js/src/extensions/themes/mmenu.themes";

//   Wrappers
@import "../../mmenu-js/src/wrappers/bootstrap/mmenu.bootstrap";

Run Gulp

Now that we've created and customized the custom-build/src/mmenu.js and custom-build/src/mmenu.scss files, we're ready to create a customized version of the plugin uing Gulp.

First (if you haven't already), install Node.js and install Gulp. Next, open up the command line, navigate to the plugin package directory and install all dependencies.

$ cd /path/to/project/mmenu-js
$ npm install

Now, run $ gulp custom --i [path], where [path] is a relative path from the plugin package directory to our custom-build/src directory. Optionally, you can also specify an output directory by adding --o [path], where [path] is a relative path from the plugin package directory to the desired output directory. Note that both the --i and --o flags should not end with a trailing slash.

$ cd /path/to/project/mmenu-js
$ gulp custom --i ../custom-build/src --o ../custom-build/dist

This will use the mmenu.js and mmenu.scss files we created in the custom-build/src directory and compile mmenu.js and mmenu.css to the custom-build/dist directory.

SCSS includes

Although the created custom-build/src/mmenu.css file now only contains CSS for the needed add-ons, extensions and framework wrappers, it might still include CSS you do not need. For example, you probably only need one theme from the themes extension. So to exclude the unnecessary CSS, lets have a look at how to opt out of CSS.

First, we need to copy the src/_includes.scss file from the plugin package directory to the custom-build/src directory.

If you'd like to use the command line, navigate to the plugin package directory and run these commands.

$ cd /path/to/project/mmenu-js
$ cp src/_includes.scss ../custom-build/src

You now have a directory that looks something like this.

project
 |- custom-build
    |- src
       |- _includes.scss
       |- mmenu.scss
       |- mmenu.js

Open the custom-build/src/_includes.scss file in an editor, the SCSS variables you see determine whether or not to include CSS for a specific purpose throughout the entire CSS framework. Set the SCSS variables for purposes you do not need to false. For example, if you want to use the white theme, you can opt out of the dark and black themes.

$mm_include_themes_dark: false;
$mm_include_themes_black: false;

Opting out of as many (parts of) add-ons and extensions as possible can drastically decrease the file size of the CSS file. Have a look at the SCSS documentation page to learn what each variable does.

Now, again, run $ gulp custom --i [path].

$ cd /path/to/project/mmenu-js
$ gulp custom --i ../custom-build/src --o ../custom-build/dist

Change the appearance

So far, we've created a custom build in which we limited the concatenated files and opted out of CSS we do not need. This is great for reducing the file size, but the menu still has the same look and feel. To change the menu appearance, lets have a look at how to override SCSS variables.

First, we need to copy the src/_variables.scss file from the plugin package directory to the custom-build/src directory.

If you'd like to use the command line, navigate to the plugin package directory and run these commands.

$ cd /path/to/project/mmenu-js
$ cp src/_variables.scss ../custom-build/src

You now have a directory that looks something like this.

project
 |- custom-build
    |- src
       |- _variables.scss
       |- mmenu.scss
       |- mmenu.js

Open the custom-build/src/_variables.scss file in an editor and make changes to the SCSS variables as desired. Have a look at the SCSS documentation page to learn what each variable does.

Now, again, run $ gulp custom --i [path].

$ cd /path/to/project/mmenu-js
$ gulp custom --i ../custom-build/src --o ../custom-build/dist