How I convinced Madcap Flare to add Separators in menus

Sometimes, Flare's capabilities and my creativity ... well, they clash. Recently, I wanted to use Flare's TopNav design for a user guide, but I also wanted to do things a bit differently from the norm.

In normal Flare-world, you can group menu items together by adding the items to a sub-group that flies out when the user mouses over it. While this works for some projects, I was working on a product that was purposely designed to be simple to use. Therefore the user guide also had to feel light, airy, and simple to use.

The basic fly-out menus felt clunky and overly complicated. I wanted something simpler. So I dreamed up menu separators that would group my data together without fly-outs.

How my creativity won out over Flare

Take a look at this screen capture from my new user guide. You can see that in my General TopNav menu, I have what looks like topics (but are not) called Networking, Stream Config, USB Camera, and Other.

These are the object of my Flare daydreams! And I call them separators.

Feel free to browse around my online user guide to get a feeling for how it works. Both the top nav menu and the individual page menus are updated with special styles for the separators.

Make this work in your project

I spent so much time looking for (but failing to find) instructions on how to do this, I thought I should share my success with the Flare community. Together I'm sure we can refine and improve on what I did!

To make it easy to follow along, I started with a new Flare project using the Top Navigation Basic2 template (from Flare 2017 r2).

Step 1: Build the project and see what you have

First, I built the vanilla Top Navigation Basic2 project. After building yours, you should see something like this in your browser:

*Tip: Right click and open images in a new tab to see them full sized.

Step 2: Add some separator topics

Open the TOC for the project in Flare and add two new unlinked topics at the same level as Feature 1, Feature 2, and Feature 3.

I had read about elusive skin properties called TOCStyles in some random articles I found about Madcap Flare. Once your skin has a TOCStyle, it appears in that list of available Style Classes for your TOC entry items.

Notice if you open the properties for one of these new topics, the Style Class list has only two choices: default and as is.

Step 3: Hack in the TOCStyle you need

Unfortunately I couldn't find any way to add these styles to my TopNav Skin. My best guess is that they are used in other output styles, like TriPane. But the HTML 5 skin editor doesn't (yet?) have a way to add or edit these styles directly.

This is where the Flare hacking happens.

Since I couldn't find a way to play nicely with Flare, I decided to go rogue and add the change I needed by using tools outside Flare. I studied some examples from bits and pieces online, then opened my project skin in trusty Notepad++ and added my own new style to the bottom skin.

The skin file to edit is:

• "your-project-folder/Project/Skins/HTML5 - Top Navigation.flskn"

The lines to add just before </Styles> at the bottom of the file are:

      <Style
        Name="TocEntry">
        <Classes>
          <StyleClass
            Name="TOCSeparator"
            Custom="true">
            <Properties>
              <Property
                Name="FontSize">1em</Property>
            </Properties>
          </StyleClass>
        </Classes>
      </Style>

 Step 4: Apply the TOCEntry style to your Separators

Now that you have the new TOCEntry style created, it's easy to apply them to your separator entries from the TOC properties dialog in Flare.

The new TOCSeparator class magically appears in the Style Class list.

Pick the new styles for both Separator 1 and Separator 2.

If you rebuild now, you won't see any changes. Go ahead and try if you like. The piece we're missing is the actual style class settings.

Step 5: Style your Separators

It took a few iterations and some debugging in the browser to get all the different styles right. But for the sake of brevity (and your sanity), I'll explain it all at once here.

First, use Notepad++ to open the stylesheet for the project:

• "your-project-folder/Resources/Stylesheets/styles.css"

Copy and paste the new style class to the bottom of the style sheet. Here's a breakdown of what the new style does:

• adds 8px of padding before the separator
• makes the separator font bold and changes the font colour
• upon mouse hover, changes the cursor to the default cursor (arrow) instead of a hand
• changes the hover background so it's the same colour as the original menu instead of changing colours when the cursor hovers over it (only necessary if your project uses this background hover element, which the template does)

The exact code added is:

/* Add an entry for "separators" in the TOC. To use this style, select the item
   in the Flare TOC and pick "TOCSeparator" as the TOC Entry style. Note along 
   with this change we needed to add the TOCSeparator entry to the Flare skin */

ul.navigation li.TOCSeparator
{
	padding-top: 8px;
}

ul.navigation li.TOCSeparator a
{
	font-weight: bold;
	color: #2a2a2a;
	/* Set the default cursor so it doesn't look like this is a link */
	cursor: default;
}

ul.navigation ul > li.TOCSeparator:hover
{
	background: #686868;
}

When you rebuild the project now and load it into a browser window, it should look like this.

When you hover the mouse cursor over Separator 1 or Separator 2 you get no background colour change, and the cursor remains an arrow. Compare this with hovering over Feature 1 or Feature 2.

The first time I got this right, I was so excited! It turned out even better than I had imagined it.

Step 6: Rinse and repeat for the side menus

Okay, it's not quite as simple as rinse and repeat for the side menus. But the goal is to also style those menus. Otherwise you'll have pretty TopNav menus, but your side menu will still look like this.

Open your stylesheet in Notepad++ again to copy and paste in a few more lines. The breakdown of the news lines is:

• add spacing before the separator menu items
• change the font weight and colour of the text (note the !important for these, I'll get into that later)
• override the cursor and background colour on hover

Here is the code for you to copy:

ul.menu li.TOCSeparator
{
	padding-top: 8px;
}

ul.menu li.TOCSeparator a
{
	/* Note that the next two items are being over-written by Flare classes. 
       Use important to right this. */
	/* This is the Flare class: ul.menu._Skins_SideMenu.mc-component li > a  */
	font-weight: bold !important;
	color: #2a2a2a !important;
	/* Set the default cursor so it doesn't look like this is a link */
	cursor: default;
}

ul.menu ul > li.TOCSeparator > a:hover
{
	/* Flare over-writes this class too, so need to make it important 
       to avoid hover decoration. */
	background: #525252 !important;
}

Once this change is saved, rebuild the target and open it in your web browser. You now have separators with some spacing, bold font, and darker colour than the rest of the side menu items.

Step 7: Tweak to perfection

Now that you have the basics working, change up the styles to match what you need in your project. Change the colour, the spacing, the font decoration, whatever you need! Have fun with it.

Side note about !important

You probably noticed that some of the menu styles had to be marked !important in the .css file. Generally speaking, web devs don't like using this declaration in their .css files. Unfortunately I didn't have the time, nor do I have the expertise to avoid doing this. For now, I added lots of comments to inform future editors of my file why I made this decision.

But maybe some of you readers have good ideas how to make this even better! I'd love to hear from you.

I hope this has been a helpful and informative post showing you how to add separators to the menus in your projects. Should you give it a try, let me know. I'd love to see how it looks for you! Leave me a comment with a link to your online help.

Happy writing!