Accordion Menu in MadCap Flare - Part One

NOTE! This solution only works for versions of Flare that are older than Flare 2017 r2. This is because Flare 2017 r2 has a different way of handling the toc and minitocs. But the good news is that Flare 2017r3 had an update that made an accordion menu possible. For details on that, see Accordion Menu for Flare 2017 r3.Have you ever wished that MadCap Flare could create a HTML5 output that has the good looks of the Top Nav skin, but with the layout of the Tri-Pane and a modern, accordion menu for the table of contents? I know I have, and so have my customers. Several clients have asked "Can't you make it look/work like our web site?". It has been a problem, because most modern web sites use some form of accordion menu and that's not really possible with Flare, not out-of-the-box anyway.But it is achievable, and in this series of posts, I'm going to share how to create the following layout, which was created by Dave Lee (https://ukauthor.wordpress.com/).

I commissioned Dave to create this layout as when I first tried, I just couldn't get it to work. Dave has more knowledge of Foundation and JQuery than me, and was able to achieve so much more, and explain it all to me too.If you are wondering why I am going over this layout again, when I posted a smartmenus solution before, let me provide a quick update. The smartmenus solution works fine if you don't use a Flare skin, but then you don't get the slide-in mobile menu. There are ways to work around this, and Dave set it up to have the toc menu show above the content on mobile. That's fine if you don't have a lot of books in your content, but my client's projects are huge and so having a large menu before the content isn't particularly user-friendly. They prefer the slide-in menu, and for large projects, I agree it is a better option. Unfortunately, the smarmenus solution does not work properly when it is used with a Top Nav skin. I'm not 100% sure why, but other Flare users have experienced the same problems - the smartmenu accordion doesn't expand properly when sub-menu options are selected and the page is re-loaded. I can only guess that it is some sort of conflict between the smartmenu and the foundation off-canvas slide-in menu that is included in the Top Nav skin (the slide-in mobile menu).

The Accordion+Drill Down Side Menu Layout

Let's have a look at the basic layout that we need. In the screenshots shown, the interface has been customised for general use by Dave, and I'm going to need to modify it a little, so will cover that in later posts.The first screenshot shows the layout on larger screens:

As you can see, there is a header that contains a search bar, a left-hand side panel which contains the contents as a multi-level accordion menu, and a main display area that contains a breadcrumb and the body content. At the bottom of the layout, there is also a footer area (shown below).

The next screenshot shows how the layout appears on smaller devices, such as smartphones:

At small sizes, the accordion menu disappears and is replaced by the mobile menu (drill down slide-in menu), which is accessed via the 'hamburger' icon in a title bar at the top of the screen. When a user selects the 'hamburger' menu, the contents menu slides into view from the left of the screen, just like it does with Flare's Top Nav output.

Overview of Creating the Accordion+Side Menu Layout

Creating this layout requires quite a bit of work, which is why I'll be explaining it in a series of posts rather than one. But I'll give a quick overview now, so that more tech-savvy readers can see what was done and go away and try for themselves.

1. Create a HTML5 project in Flare and choose a Top Nav skin. We're not actually going to use a skin, but Flare won't build the output unless there is a skin file in the project.
2. Edit the Target so that it does not use a skin for the project (General > Skin: none). Note that you do use skins for the Menu, Search Bar, and Search Results. You will need the menu skin, so make sure that the Menu is set to Menu.flskn (that's the menu skin we will use in this solution, but you can use a different menu skin if you wish - you will just need to change references to menu.flskn when they appear later).

1. Save the Target. With the General skin set to (none), you will be able to reference the full Foundation framework from the master page (more on this in later posts).
2. Download the Foundation framework from http://foundation.zurb.com/sites/download.html/ and add it to the Resources folder in your Flare project. I recommend that you download the Complete framework as it contains the accordion menu and slide-in menus we need.If you are wondering why you need to download Foundation when Flare already uses it, it is because Flare only uses parts of the framework in the Top Nav skin. With this layout, you won't be using a skin, so you need to include the Foundation framework in our project, as that's where all the code and css for the menus is stored. Also, the Top Nav's version of the Foundation framework would clash with the full version of Foundation.
3. Create a script that converts the output of Flare's menu proxy into a ul list that uses the classes required for the Accordion menu. The script should convert the proxy ul list once and then clone (copy) the result to the drill-down menu div. (This is a script that Dave created for me and is something I will cover in later posts).
4. Create the layout for the entire HTML5 output in a master page. For this, you need to use the Foundation grid (again, something that I will cover in later posts). The layout needs to:
5. Reference the foundation .css stylesheet (in the downloaded Foundation files).
6. Reference the project .css stylesheet that you create in Flare.
8. Include a div for the title bar that contains the 'hamburger' icon and is only available on small screens (small, medium, large, being sizes that come from the Foundation grid).
10. Include a div for the 'hamburger' icon.
12. Include a div for the off-screen area.
14. Include a div for the slide-in menu, this needs to be inside the div for the off-screen area. Note that you do not add a menu proxy inside this div. That's because we will use 1 menu proxy in the master page (in the accordion menu), manipulate it once, and then copy the results here.
16. Include a div for the content that is included in the on-screen area (this is everything you will see on the page).
18. Include a div for containing the page content. This needs to be inside the div for the on-screen area.
20. Include a div row for the header and search box.
22. Include a div for the header.
24. Include a div for the search bar.
26. Include a search box proxy inside the search bar div.
28. Include a div row for the accordion menu.
30. Include a div for the accordion menu.
32. Include a menu proxy inside the accordion menu div.
34. Include a div for the main content of the topic.
36. Include a breadcrumb proxy inside the main content div.
38. Include a body proxy inside the main content div.
40. Include a snippet for the footer (after you have closed the main content div).
42. Include references to the scripts that are needed to run Foundation. These are included in the Foundation files:<script type="text/javascript" src="../foundation/js/vendor/what-input.js"></script><script type="text/javascript" src="../foundation/js/vendor/foundation.js"></script>
44. Include a reference to a script that converts the output of the menu proxy in Flare into the format needed for the accordion menu and slide-in menu. .

When all of that is in place, you can work in Flare in the usual way, creating topics and building your TOC. When you build and display the output, it will be shown in the customised Accordion+Drill Down Side Menu layout.In full series of posts, I will look at the steps in the process in more detail.Next, I will explain how to add the full Foundation framework to a Flare project and how to set up your project to use it. See the next post in the series: Accordion Menu in MadCap Flare - Part Two.