Accordion Menu in MadCap Flare - Part Three

This is Part 3 of a series of posts on how to create the following layout, complete with accordion menu and slide-in drill-down menu, in MadCap Flare.

If you missed the previous parts, see:

• Part One
• Part Two

In Part 3, we're mostly going to be looking at how to create the master page for this layout, but before we get into that, it is important to know how the Foundation grid works.

WARNING! This is a long post, so expect boredom to kick in at some point!

Understanding the Foundation Grid

Before I start explaining the Foundation grid, let me just say that, at the moment, I use Flare 11. I believe there is a responsive layout feature in Flare 12 that uses a similar approach to Foundation (it may even be Foundation), but I'm not sure how that works. I don't expect there to be any conflict between what we are doing with Foundation and how the responsive layout in Flare 12 works, but if there is, please post in the comments.Now, on to the Foundation grid...The Foundation grid is really easy to use, but it can be a little confusing at first, especially if you are used to laying out divs without any sort of grid in place. I normally lay out divs in percentages of the viewport's width, with floats for positioning. Thinking that way really muddied the waters for me when I was trying to understand the Foundation grid. So before we get going, forget about floats etc., for now.By the way, if you are an ISTC member, Matthew Ellison has written an article on the Foundation grid in the Summer 2016 issue of Communicator. (Please note that is the UK organisation, ISTC, not the US-based STC). Matthew has also posted the article on the UA Europe site, here: http://www.uaeurope.com/articles/ResponsiveLayoutMadCapFlare.html.The Foundation grid divides the screen into 12 columns by default (you can't see the columns, but they are there in the background).

You create your layout by adding rows, and then adding one or more divs to each row. Think of the divs as cells. In the image below, a div has been added to every column in 3 rows.

A div can fill the entire width of the row (12 columns) or only part of the width (1-11 columns), and you tell it how many columns to cover in the code. It is a lot like creating a table in Word, really, only you are stuck with 12 columns - you add as many rows as you want and within each row, as many cells as you want. In the image below, you can see:The top row has 5 divs. From left-to-right, div 1 is 3 columns wide (cols 1-3), div 2 is 1 column wide (col 4), div 3 is 1 column wide (col 5), div 4 is 1 column wide (col 6), and div 5 is 6 columns wide (cols 7-12).The middle row has 4 divs. From left-to-right, div 1 is 2 columns wide (cols 1-2 inclusive), div 2 is 8 columns wide (cols 3-10 inclusive), div 3 is 1 column wide (col 11), and div 4 is 1 column wide (col 12).The bottom row has 3 divs. From left-to-right, div 1 is 4 columns wide (cols 1-4 inclusive), div 2 is 4 columns wide (cols 5-8 inclusive), and div 3 is 4 columns wide (cols 9-12 inclusive).

The key thing is that the grid is always 12 columns, it is how we divide those columns up into divs that changes. You can create any combination you like, but it cannot exceed 12 columns. If the divs in a row are less than or greater than 12 columns in total, the layout will mess up, so stick to 12 and stay on the grid.Before we look at how this is actually coded, we need to look at the three different sizes: small (smartphones), medium (tablets) and large (desktops). These are the three sizes we can specify when defining our rows. For example, if you want a row to be 6 columns wide on a desktop but only 3 wide on a tablet, you set the large size to 6 and the tablet size to 3 when you define the size in the code.I know what you're thinking - "well how do I define the frickin' code?". We'll look at that as we delve into Dave's master page.

The Master Page

Back to our Flare project. We're going to look at how Dave has created the layout to work in the Foundation grid, and for that I'll break it down into chunks. (As long as Dave agrees, I will post his template project up when I have documented the script part, which will be the next post in the series).The top part of the master page is the usual stuff you find in any master page - declaring the xml version, the location of the schema, etc.

<?xml version="1.0" encoding="utf-8"?><html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="12" MadCap:lastHeight="658" MadCap:lastWidth="829">

The next part is the head, and in here we have three links to files.

<head><link href="../foundation/css/foundation.css" rel="stylesheet" type="text/css" /><link href="../foundation-icons/foundation-icons.css" rel="stylesheet" type="text/css" /><link href="../Stylesheets/TopicStyles.css" rel="stylesheet" type="text/css" /></head>

The top one is a link to the foundation.css stylesheet that is one of the Foundation files you downloaded in part 1. The second one is a link to the foundation-icons.css stylesheet, which is optional. Dave included the Foundation icons in this project and uses them in the footer. If you want to use them too, you can download them from here: http://zurb.com/playground/foundation-icon-fonts-3. Just add them to the Resources folder in Flare, like you did with the Foundation framework files.

The final link is a link to the TopicStyles.css stylesheet, which is the stylesheet being used for the Flare project. It is important that you don't edit the TopicStyles.css stylesheet in the Flare editor. This is because of a bug in the editor. As Dave Lee told me: "If you edit anything in that stylesheet using Flare's editor, it will substitute the full stop in 'not(.' with 'not(\00002E'. It's a bug in Flare, it will break a few things which are valid CSS. For the same reason, never edit an external stylesheet (like Foundation) in Flare."Now we get to the actual layout. The first part we are going to create is the menu bar that will only appear on small screens, such as smartphones, and the slide-in menu. To create the slide-in menu, we use the 'drill-down menu' and to create the slide-in functionality, we use the 'off-canvas wrapper'. These are both available in the Foundation files (that we added to the Flare project in Part 1). You can find information on both of these at the Foundation site:

• http://foundation.zurb.com/sites/docs/off-canvas.html
• http://foundation.zurb.com/sites/docs/drilldown-menu.html

We start with the body element, and then add a div with the class "off-canvas-wrapper". This div is the container for the entire off-canvas area. The off-canvas-wrapper feature works by splitting the display area for the content into three containers:

• The "off-canvas-wrapper" that contains everything
• The "off-canvas-wrapper-inner" that will contain the menu and the title bar for accessing the menu.
• The "off-canvas-content" that will contain the main content of our page (the accordion menu, the header, the topic, etc.).

Let's get started.

1. Create a new Master Page in Flare and name it: Foundation-responsive-offcanvas.If you like, you can give it a different name, but you will need to make sure you swap out any references to Foundation-responsive-offcanvas that appear later in these posts.
2. Display the master page in the Text Editor view, as that's going to make it easier to get the code right.
3. Add the declaration and head sections that we have already discussed:<?xml version="1.0" encoding="utf-8"?><html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="12" MadCap:lastHeight="658" MadCap:lastWidth="829"><head><link href="../foundation/css/foundation.css" rel="stylesheet" type="text/css" /><link href="../foundation-icons/foundation-icons.css" rel="stylesheet" type="text/css" /><link href="../Stylesheets/TopicStyles.css" rel="stylesheet" type="text/css" /></head>
4. Add:<body><div class="off-canvas-wrapper"><div class="off-canvas-wrapper-inner" data-off-canvas-wrapper="">With the code above, you are creating the body element and adding the off-canvas-wrapper div (contains everything) and the off-canvas-wrapper-inner div (contains the menu title bar and the slide-in menu). The off-canvas-wrapper-inner div needs the data-off-canvas-wrapper=""' attribute.
5. Add:<div class="title-bar hide-for-medium"><div class="title-bar-left">The title-bar class is the container for the menu title bar. We only want it to appear on small devices, so you need to add 'hide-for-medium' when you create the div. The 'hide-for-medium' is an instruction to the browser to hide this div, and its children, on screens that are medium or above in size. Remember that the Foundation grid has three sizes - small, medium, and large, which you can think of as phone, tablet, and desktop.
6. Add:<button class="menu-icon" type="button" data-open="offCanvasLeft"></button><span class="title-bar-title">Menu</span></div></div>With the button class, you are creating the 'hamburger' button that will open and close the slide-in menu. The menu-icon references the menu-icon class in the foundation.css stylesheet. The hamburger icon isn't a graphic, it is created in code in foundation.css (there are a variety of attributes in the menu-icon class and its child classes).The type=button tells the browser that this is a button element, and the data-open="offCanvasLeft" is what they call a 'click trigger' - it tells the browser to open the 'offCanvasLeft' element when the button is selected. We haven't defined the 'offCanvasLeft' element yet, but it is coming up.The span class references the title-bar-title class in the foundation.css, and this class defines the look of the text. 'Menu' is the text that will appear in the span, which is next to the button.The two closing divs close the title-bar-left and title-bar hide-for-medium divs respectively. That's our title bar done.

1. Add:<div class="off-canvas position-left" id="offCanvasLeft" data-off-canvas="">This div contains the off-canvas left element, which will contain the drill-down menu. It references the 'off-canvas position-left' class in the foundation.css stylesheet, and that particular class sets the position of the off canvas element (there is a position-right equivalent too). Note that it has the id offCanvasLeft, which is the element we told the button in the title bar to open. The off-canvas position-left div needs the data-off-canvas=""' attribute.
2. Add:<div id="nav-drilldown"></div></div>With the code above, you are creating a div that will contain the drill-down menu, and then closing it, and finally, you close the offCanvasLeft div you opened previously. As you can see, there is no menu in the nav-drilldown div....yet.The reason there is no menu in place is that the script we use later will copy the 'tweaked' output from the menu proxy and paste it into this div for us. With this layout, we are using two menus - the accordion menu and the drill-down menu - and they both contain the same information, so it is more efficient to 'tweak' the menu proxy output once, and then copy the result into place. More on that later.
3. Add:<div class="off-canvas-content" data-off-canvas-content=""><section id="page-content">Here, you are creating the off-canvas-content div that will contain everything that isn't part of the slide-in drill-down menu. The div has to have the data-off-canvas-content="" attribute. The section id ="page-content" part creates a section, which is slightly different to a div. A section is used to group content that is semantically related, whereas a div is for grouping content for styling purposes.Now we are getting to the main display area layout.
4. Add:<div class="row" id="header-area"><div id="header-title"><h1>Header title</h1></div>What's going on here then? Well, you're adding the first row to the grid, and you're giving it an identity (header-area). Then you are creating a div within that first row, and you're calling that div 'header-title. Then you are adding the text 'Header title' as a heading, with heading level 1. Finally, you are closing the header-title div, but leaving the header-area row open.
5. Add:<div id="header-search"><MadCap:searchBarProxy /></div></div>What you're doing here is adding another div, called 'header-search', and it is still in the header-area row (as the div for that row is still open). Then you are adding a Flare search bar proxy, which will provide the search bar for our layout. After that, you close the header-search div, and close the row.You've now created this part:

1. You haven't formatted the background colour or anything yet, but you have the layout.
2. Add the next row, which will contain the accordion menu on the left and the topic body on the right:<div class="row">
3. Now to create the accordion menu stuff. Add:<div class="show-for-medium medium-4 large-3 columns" id="nav-accordion"> <MadCap:menuProxy data-mc-skin="/Project/Skins/Menu.flskn" mc-linked-toc="/Project/TOCs/Master.fltoc" style="mc-toc-depth: -1;mc-context-sensitive: False;mc-include-parent: True;mc-include-siblings: True;mc-include-children: True;" /></div>Look at the div with id=nav-accordion. This is the div that will contain the accordion menu, which should only be shown on the left side of the screen, and only on suitably large tablets and desktops. With 'show-for-medium', you tell the browser to only show everything in this div on devices that have a screen size that is medium or above. On small screens, the div, and everything inside that div, will not be shown. The 'medium-4 large-3 columns' part is also important - it sets the width of the div to 4 columns on medium-size screens, and to 3 columns on large-size screens. This is the syntax needed for showing the div and setting the width in the Foundation grid.Inside the nav-accordion div, you have added a Flare menu proxy. The menu proxy provides the ul list that we will use for the accordion menu. The ul list is generated by Flare based on the toc structure, but the output isn't in the format that is needed for the Foundation accordion menu. We're going to use a script to convert the output into the required format later.The Flare menu proxy is set to use the Master.fltoc as its table of contents, which is fine if your toc is called 'Master'. If your toc is called something else, you will need to change the referenced toc here too, but that's the same whenever you use the menu proxy.The other parts of the menu proxy element are defining the settings for the menu proxy. To be honest, it is easier to set and edit these by using the Menu Proxy Editor (switch the master page to the XML editor, right-click on the menu proxy, and select Edit Menu Proxy).You then closed the nav-accordion div.
4. Add the topic container, which is going in the right-hand side of the same row as the accordion menu:<div class="small-12 medium-8 large-9 columns" id="topic-content"> <MadCap:breadcrumbsProxy /><MadCap:bodyProxy /></div></div>Here, you begin by adding a div to contain the topic content. On small screens, the accordion menu isn't going to be shown as we have the slide-in drill-down menu instead. So, the first thing you're doing here is setting the width of the div for small screens to 12. This means on small screens, the topic-content div will be full width (12 columns wide, and we are using a 12-column grid).

1. After creating the topic-content div, you added a Flare breadcrumbs proxy and the Flare body proxy. Again, if you wanted to edit the properties of these, it is probably easier to switch to the XML editor and edit the proxies from there. You then closed the topic-content div and also the row, which was still open.
2. Nearly done. Now to add a footer. For the project I commissioned, Dave decided to use a snippet for the footer, so let's go with that for now. I will add a section at the end of this post to explain the formatting of the snippet.To add the footer snippet, enter:<MadCap:snippetBlock src="../Snippets/Footer.flsnp" />
3. You need to close the open section and divs next, before you reference the scripts that are needed. Add:</section></div></div></div>The /section closes the open section element that you created for the page content. The divs after that close the page content div, the off canvas div, the off canvas wrapper inner, and the off canvas wrapper.
4. For the last part of the master page, you need to reference the scripts that are needed. Add:<script type="text/javascript" src="../foundation/js/vendor/what-input.js"></script><script type="text/javascript" src="../foundation/js/vendor/foundation.js"></script><script type="text/javascript" src="../Scripts/foundation-menu-off-canvas-initialisation.js"></script></body></html>The what-input.js and foundation.js scripts are needed by any project that uses Foundation, so that's why they are added. The foundation-menu-off-canvas-initialisation.js script is a jquery script that converts the Flare menu proxy output into the format needed for the accordion menu and drill-down menu (it also copies the converted output into the empty nav-drilldown div that you added early on in the master page). You don't have the foundation-menu-off-canvas-initialisation.js script yet - I will cover that in the next post.After the script references, you close the body and html elements and the master page is complete.
5. Save the master page.

The Footer Snippet

In the footer section of the master page, you referenced a footer snippet file rather than adding all the code for the footer. That's just how Dave created the layout, and you could add the code to the master page instead if you wanted. If you want to follow suit and use a footer snippet, here's what you need to do.

1. In Flare, create a new snippet in the Snippets folder and name it Footer. You can call it something else or add it to a different folder if you want, but you will need to change the master page reference to the Footer.flsnp file to match.
2. Use the Foundation syntax and regular HTML/CSS to define the layout for the footer. An example is included below.
3. Save the snippet.
4. Make sure the master page references the correct snippet for your footer.

Example:I'll show you how to create the footer Dave made, which looks like this:

The code for this is:

<?xml version="1.0" encoding="utf-8"?><html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="401" MadCap:lastWidth="945"><body><div class="row" id="footer-area"><div class="small-12 medium-4 large-6 columns"><h4>Footer text</h4><p>Some content in the footer. This section is a bit larger than the others.</p><p style="font-size: 3rem;"><i class="fi-social-linkedin"></i>&#160;<i class="fi-social-google-plus"></i>&#160;<i class="fi-social-facebook"></i></p></div><div class="small-6 medium-4 large-3 columns"><h4>Footer links 1</h4><ul><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li></ul></div><div class="small-6 medium-4 large-3 columns"><h4>Footer links 2</h4><ul><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li></ul></div></div></body></html>

You can probably work this out for yourself by now, but let's skim through it, just in case.We start the snippet file with the '?xml version' and 'html xmlns:MadCap' parts that you get in all Flare files:

<?xml version="1.0" encoding="utf-8"?><html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="401" MadCap:lastWidth="945">

The next line creates a row named footer-area:

<div class="row" id="footer-area">

The next line creates a div in the footer-area row, and the div is 12 columns wide on small screens, 4 columns wide on medium screens, and 6 columns wide on large screens.

<div class="small-12 medium-4 large-6 columns">

The next few rows add a heading 4 of 'Footer text' to the div, along with some paragraph text and some icons.

<h4>Footer text</h4><p>Some content in the footer. This section is a bit larger than the others.</p><p style="font-size: 3rem;"><i class="fi-social-linkedin"></i>&#160;<i class="fi-social-google-plus"></i>&#160;<i class="fi-social-facebook"></i></p></div>

The icons are added by using i class and classes that are included in the foundation-icons.css. If you didn't download foundation-icons, you won't have access to these icons, but you can add images and reference those using regular img elements instead if you wish. The /div closes the div that contains the Footer text heading and the icons. The row div is still open.The code we've looked at so far creates this bit:

The following lines create the second div container, the Footer links 1 heading, and the bullet list:

<div class="small-6 medium-4 large-3 columns"><h4>Footer links 1</h4><ul><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li></ul></div>

This second div is 6 columns wide on small screens, 4 columns wide on medium screens, and 3 columns wide on large screens. The /div closes this new div, but the row div is still open.The code so far has created:

The third div and second bullet list is created by using:

<div class="small-6 medium-4 large-3 columns"><h4>Footer links 2</h4><ul><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li><li>Footer links.</li></ul></div>

This works in the same way as the previous bullet list section, only it appears to the right of the previous bullet list.The following code closes the row, the body, and the html:

</div></body></html>

I don't know about you, but I'm sick of the sound of my own voice, so let's call it a day on this post. In the next one, I'll go through the script that converts the menu proxy into the format needed by the Foundation menus. That's the last key ingredient you will need. After that, it will just be a case of looking at the stylesheet and making adjustments, looking at how the Foundation stylesheets have been created, and also a quick look at some of the limitations of this layout.Bye for now!Part 4 is now live: Accordion Menu in MadCap Flare - Part 4.