Accordion Menu in MadCap Flare - Part Six

This is Part 6 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, here are links:

In this post, I'm going to cover a few of the problems I ran into when I tried to implement the solution on an existing project. I'll list the issues first, so that you can skip to parts that are relevant to you:

Can't Edit TopicStyles.css in Flare?

There is a bug in the Flare editor that means if you edit a non-Flare css file, it will cause incorrect code when saved. This is a problem in Flare 11 - it may have been fixed in Flare 12. I have not upgraded yet, so if it still persists in 12, let me know in the comments. The problem is that the Flare editor substitutes the full stop (period) in 'not(.' with 00002E', which breaks a few things that are valid CSS.This can be a bit of a problem when you have to hand over the project to other users, as they may not be aware of the limitation. Also, it is a bit of a downer if you prefer to use the Flare editor because you're not so comfortable editing css as code. I usually prefer editing css as code, but I do use the editor for some editing, especially for linking the stylesheet to files.The workaround I used was this:

In the Stylesheets folder, create a new folder and call it something that puts people off editing the files inside. I called mine 'Do Not Edit'.
Move the TopicStyles.css file into the 'Do Not Edit' folder, and when prompted, allow Flare to update the links to the file.
Rename the TopicStyles.css file to something that indicates that it is for the foundation layout. I named mine 'Foundation_LayoutStyles.css'.
Create a new stylesheet directly in the Stylesheets folder. You can call it anything you like. I called mine <customer name>_TopicStyles.css. I've blurred out the customer name below, but you get the idea.

The Foundation_LayoutStyles.css defines all of the settings that Dave tweaked for the layout, so you can leave those as they are, or you can make alterations to suit your needs. We're going to use the <customer name>_TopicStyles.css for defining the font styles, divs, etc., that you want to use in your topics. You will be able to edit the <customer name>_TopicStyles.css in Flare's editor without any issues.
You need to get the browser to use the <customer name>_TopicStyles.css styles after the Foundation_LayoutStyles.css styles. This will ensure that the formatting in the <customer name>_TopicStyles.css takes precedence (well, mostly - they will follow the cascading rules of all css styles, and this isn't always as simple as 'last setting for style=style used').
To get the browser to use the <customer name>_TopicStyles.css styles, edit the foundation-responsive-offcanvas Master Page. Add a link to <customer name>_TopicStyles.css in the <head> section, after the Foundation_LayoutStyles.css file. The order is important, as the browser will apply the stylesheets in order, starting at the top and working its way down.
You also need to edit the link to the Foundation_LayoutStyles.css file so that it includes the 'Do Not Edit' folder. Remember, you moved the Foundation_LayoutStyles.css to the new 'Do Not Edit' folder (or whatever you called it) earlier in this process.
Your head section should now have something like this:<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/Do Not Edit/Foundation_LayoutStyles.css" rel="stylesheet" type="text/css" /><link href="../Stylesheets/CustomerName_TopicStyles.css" rel="stylesheet" type="text/css" /></head>
Save the Master Page.
Use the Flare editor to edit <customer name>_TopicStyles.css. In this stylesheet, you can define the font styles, etc., for your topics in the same way as you would in a built-in Flare project.

Topics Don't Include Formatting in Flare?

The Foundation menu layout uses a Target that has no skin and the Master Stylesheet set to (default). As a result, the topics in the project are not associated with a stylesheet. This can be a bit of a problem if you want your topics in Flare to look similar to how they will appear in your HTML5 output. But there's an easy way to fix it:

Select View>File List.

Set the Filter to Topic Files (*.htm;*.html). Flare lists all of the topic files in your project.
Hold down Shift (or Mac equivalent) and select all of the files in the list.
Right-click and select Properties to display the Topic Properties window.
Select the Topic Properties tab.
Set the Stylesheet to the stylesheet that you are using to contain the topic formatting styles. For example, <customer name>_TopicStyles.css.

Flare will associate all of the topic files with the stylesheet, but importantly, the Target will still have its Master Stylesheet set to default. When you edit the topics in Flare, they will now use the styles from the chosen stylesheet and appear as you would expect to see them in the output. Well, a close match - what you see in Flare's editor isn't always the exact thing you will see in a browser, but most of the time it is right.

Select OK.

Foundation Menu Not Working on iPads, iPhones

This was a deal-breaker for my client - the Foundation menus just wouldn't work on their iPads and iPhones. A bit embarrassing, as I don't have an iPhone or iPad to test on (I'm android-only at the moment). Thankfully, the web developers that help me with lots of little niggles on my site were able to help (Web Book Studio - you can find them here on freelancer.com).Web Book Studio looked into the problem and pinned it down to a missing line of code in the foundation.css file, provided in the Foundation download. The missing line is:

-webkit-overflow-scrolling: touch;

and it needs to go before the closing } at line 2126.You can edit it yourself in a text editor and then paste it in place of the foundation.css file in the project. The location for the file is:Content\Resources\foundation\cssI wasn't able to test it myself, but Nita Beck took a look at a test site on her iPad and iPhone and reported that they both work as expected. Thanks, Nita.

Foundation Menus Not Displayed

Of all the problems I encountered, this one was by far the most frustrating. I triple-checked all the Foundation stuff was right, went through the Master Page with a fine tooth-comb and ran build after build. Annoying, because the solution was so simple.The problem was that the Foundation menus just weren't appearing. All of the styles I'd set in the project were right, but the menu was just an unformatted list sitting at the top of the page. It was caused by the Project Properties having settings in place from the previous version of the project. To fix it, all you need to do is:

Display the Project Organizer.
Right-click on Project, right at the top.
Select Project Properties.
Select Defaults.
Set the Master Toc to the Toc you want to use for the project. This has to match the toc that is used to create the accordion menu and drill-down menu.
Set the Master Page Layout and Master Stylesheet to Default.
Select OK.

That should do the trick. If it doesn't, there is something wrong in the Master Page, the stylesheets, the Target, or the foundation files are missing. Go back through the various posts in this series and try and find out what is wrong.Okay, that just about wraps this series up. Hopefully, you have enough information to get the demo Foundation menu project up and running and to start customising it to meet your own needs.I don't have time to offer support for this, but if you have questions, run into problems, or have suggestions, by all means add a comment or post to the MadCap forum. I'll do my best to help if/when I can.Now that I have Foundation menus working and Smartmenus working, I'm wondering if it might be possible to get Flare topic content into tabs. That's a project for another day.