New feature with Off-canvas Menu

On way to new release 4.5.0, my main goal is to add an off-canvas menu to the AsciiDoc-Bootsrap backend. See FR#17

But this is not yet the final implementation. I’ll try to explain the base concept to include :

• an off-canvas menu with jquery plugin https://github.com/BeSite/jQuery.mmenu

• generation of table of contents with jquery plugin https://github.com/dcneiner/TableOfContents

to the standard AsciiDoc User Guide.

• 1 First, generate the user guide by invoking following command:

asciidoc -a scriptsdir=javascripts -a stylesdir=stylesheets -a linkcss doc\asciidoc.txt

• 2 Remove the default AsciiDoc TOC: remove lines

<script type="text/javascript" src="javascripts/asciidoc.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>

• 3 Add external resources: https://github.com/BeSite/jQuery.mmenu, https://github.com/dcneiner/TableOfContents, https://github.com/FortAwesome/Font-Awesome, https://github.com/jquery/jquery

in the head of html

<link rel="stylesheet" type="text/css" href="jquery.mmenu/css/jquery.mmenu.all.css" />
<link rel="stylesheet" type="text/css" href="font-awesome/css/font-awesome.css"/>

at bottom of html body

<script type="text/javascript" src="javascripts/jquery-1.11.2.min.js"></script>
<script type="text/javascript" src="jquery.mmenu/js/jquery.mmenu.min.all.js"></script>
<script type="text/javascript" src="javascripts/jquery.tableofcontents.min.js"></script>

• 4 Add the TOC menu after main title (div id="header") and before contents of document (div id="contents")

<nav id="menu">
    <ul id="toc">
    </ul>
</nav>

• 5 Install the basic Table Of Contents generation (at bottom of html body)

<script type="text/javascript">
$().ready(function () {
    $("#toc").tableOfContents();
});
</script>

• 6 But we want more on this TOC. Here are some private custom choices

<script type="text/javascript">
$().ready(function () {
    $("#toc").tableOfContents(
        null,
        {
            startLevel: 2,    // H2 and up
            depth:      2,    // H2 through H3,
            topLinks:   true,
            topLinkClass: 'navicon',
            topLinks: '<i class="fa fa-bars"></i>'
        }
    );
});
</script>

Custom styles (with default and custom class name)

a.toc-top-link, a.navicon {
    right: 0;
    position: absolute;
}

Do not forget to add the id="toc-top" on body element.

• 7 Add the off-canvas menu handler

<script type="text/javascript">
$().ready(function () {

    var $menu = $('nav#menu'),
        $html = $('html, body');

    $menu.mmenu({
        counters: true,
        extensions: ["widescreen", "theme-dark", "effect-slide-menu"],
        offCanvas: {
            position  : "left",
            zposition : "back"
        }
    });

    var $anchor = false;
    $menu.find( 'li > a' ).on(
        'click',
        function( e )
        {
            $anchor = $(this);
        }
    );

    var api = $menu.data( 'mmenu' );
    api.bind( 'closed',
        function()
        {
            if ( $anchor )
            {
                var href = $anchor.attr( 'href' );
                $anchor = false;

                //    if the clicked link is linked to an anchor, scroll the page to that anchor
                if ( href.slice( 0, 1 ) == '#' )
                {
                    $html.animate({
                        scrollTop: $( href ).offset().top - 20
                    });
                }
            }
        }
    );

});
</script>

• 8 Add the hamburger menu open facility on right side of main title (between h1 opening and closing tags)

<a class="navicon" href="#toc-top"><i class="fa fa-bars"></i></a>

• 9 Adapt menu style to be correctly displayed even on very small devices

.mm-menu {
    width: 70%;
}

• 10 And bind action to hamburger menu

<script type="text/javascript">
$().ready(function () {

    $("a.navicon").click(function(e){
        e.preventDefault();
        api.open();
    });


});
</script>

Full source code and demo available at http://www.laurent-laville.org/asciidoc/toc-mmenu/

Published by Laurent Laville on 2015-06-05