Monday, December 07, 2015

Madcap Flare 11 - HTML5 Output without a Skin? Imposibruu!

If I had a blog dedicated to tech writing, I would definitely post this on it. But since this is my general-purpose-geek-whatever-goes-blog, it comes to reason that "miscelaneous" stuff would come here, right?

In this post I'll take you on a short adventure I've recently had while trying to deeply customize the HTML5 output generated by MadCap Flare 11, after recently upgrading to it from version 7. If you're familiar with Flare, you know that doing Web output can be pretty involved - there are a lot of moving parts, including Master Pages, Skins, Stylesheets and Proxies, to name a few.

Essentially, the goal here is to provide you with a blank canvas where you can customize, almost 100%, the HTML5 output generated by Flare. This can be super useful if you're a) a web designer yourself or b) have a web designer available to do that work for you. And, it becomes almost indispensible if you have a "corporate" style that you want your documentation to be as close to as possible.

There's only 2 things that are really required to make this work as an example. The rest of the "useful" stuff we'll add later:
  1. A Master Page. This is where you'll add your design, around the body proxy.
  2. The Target needs to be in HTML5 and NOT use a skin. 
Sounds simple does it not? Actually, it is, once you've figured out what's necessary - I've done that work for you, you're welcome! Let's dig deeper.

The Master Page

So the Master Page is just HTML code that's inserted around your body text, on each file that's created in your output. We're going to use this to create our "design". Let's start with something really, really basic just to give you a feeling of how "simple" it can be. Create a Master Page by going to the Project Tab, then going into New -> Add Master Page. Give it a name, like, say, "No-skin". (Note: You might already have a "basic" Master Page. If so... skip on to the next section, as the build-in master pages are pretty much built the right way!)

Go to the "Text Editor" view and paste the code provided: Pastebin link

If you've ever worked with HTML you'll recognize just about everything here, with the only exception of the MadCap:bodyProxy element. This is basically the placeholder for the contents of your topic, aka everything in the tag of that topic.

Alright, now this is a very basic Master Page that contains nothing in terms of navigation, but we can add that in a second. Let's move on to the next step.

An HTML5 Target that doesn't use any skins

So now we get to the interesting part: building the target. Go to Project -> New -> Add Target. Make sure the Output Type is set to HTML5, give it a name (my-user-guide, or whatever) and click Add.

In the properties, the following things need to be change:
  • In General, ensure that the Master TOC and Master Stylesheet have been attributed values.
  • In Skin, use the drop-down to change "Skin" to "(none)".
  • I Advanced, go to Master Page and change it to Resources/MasterPages/No-Skin (or whatever you named it).
  • If you want to change other options like conditions and variables, go ahead. 
And now the fun part. Save this target, and hit Build. After the build is done, click on View and open it in your favorite browser. Should look something like this:

Adding navigation and other proxies

So the above preview looks really dull, right? Of course it does, because there's no navigation, no toolbar... Only the header (I added to my master page as above), and the contents of one topic. 

Now what we can do is start adding proxies into the Master Page, to start giving us some useful stuff to work with! In the XML Editor view of the Master Page, you can insert the following proxies:
  • The Breadcrumbs proxy (You are here!)
  • The Topic Toolbar proxy (which shows links such as highlighting, print and such)
  • The Search Bar proxy which adds the search box and button
  • The Menu proxy, which is used to display the Table of Contents. When adding the TOC, to start with I suggest unchecking Context sensitive and changing Levels to Show to (all). You can customize it later on. 
Alright... now we're talking! Check this out:

So everything we really need is here - we just need to style it properly! Obviously, this is where the expertise of a web developper normally comes in. But I'm a great gal so I'll provide you with a complete project at the end of this post. In the meantime, here's what it looks like with a bit of HTML tweaking and some CSS styles:

Ok so in this case I'm reproducing more or less the "typical" webhelp tripane design. But it doesn't need to be this way. You could place the TOC on the right in a floating sidebar, you could have the TOC drop-down from the left or right or have it fly around avoiding the user's cursor... whatever, basically. My point here is that the sky's the limit and your web developers will be happy to know that they can tweak this to the point where it will look like what you want, from top to bottom, start to finish. And, by the way, you can add conditions, variables and anything else in the Master Page that you would in a normal topic. So that's awesome too.

Custom Search Results Page

One issue I came up with later in my design is that the Search Results page wasn't using the Master Page, and I wasn't sure how to proceed. Some help from the Madcap forums later, the solution came about: Create a new topic inside the Resources/MasterPages folder of your project (I called it "searchresults.html", the name doesn't matter), and simply add the Search Results Proxy inside of this topic: double-click on it, remove all the contents then go to Insert -> Proxy -> Search Results Proxy. I believe it's a workaround for a bug (as this writing, in Flare 11). But that topic in a custom location is all that's necessary, thankfully.

Need more help?

Post on the Madcap Flare forums, or comment below!

6 comments:

  1. Hi Evelyne, thanks for this post! I've basically come up with the same thing for some product documentation that I'm working on, and it helps to see that someone else is doing something similar successfully :)

    What we're currently planning to do is create HTML5 build targets for each of our products (we have 8-10 products) from the same Flare project, using the same Master page. They all need to be built independent of each other because they are all on different schedules. I'd like to have some kind of "docs landing page" that links out to all the different products that looks entirely different, kind of like the HTML top nav template. Should that page it be a static page? Or, is there a way to somehow create a TOC that doesn't actually try to build all of the references in it?

    I'm coming from the DITA world where you would build all your products separately and then have a master TOC that has navrefs, which are basically pointers to the separately built doc sets. I can't figure out if Madcap has this kind of concept!! Thanks for any insight!

    ReplyDelete
    Replies
    1. Oh by the way if you want to see the result of this method (I mean, the "no skin + master page" at work, after it's passed through a team of web devs... here it is:

      http://help.objectiflune.com/EN/planetpress-connect-user-guide/1.4/Overview.htm

      I think they did an awesome job!

      Delete
  2. Hi Carrie! I'm happy to see I'm not the only one who's found some use for this!

    I have found myself in the situation that you describe, and there are two things that you can do, depending on your needs.

    If you don't need to link between different outputs, you can create a landing page. We made one manually, as there isn't any way to do it directly in Flare. And it makes for a much nicer page with a lot of controls with links to other resources. You can check out the one for my employer's documentation here: http://help.objectiflune.com/EN/ (one of our web integrators made this one, it's awesome!)

    If you do need to link between the different outputs for the products, you'll need to add something to the master page for this. A drop-down, for example, or just links directly in the top navigation bar. A sprinkle of JavaScript and you're done.

    So yes, this is manual work. I wouldn't personally rely on any "automated" tools to make a landing page for me, especially since I'm surrounded by teams of web developers and integrators that eat this stuff up for breakfast!

    ReplyDelete
  3. Awesome, thanks for the feedback and information! I was searching and searching and just not sure if I missed some important function! :)

    ReplyDelete
  4. Hi Évelyne,
    I was experimenting with this approach, but I was wondering how to modify the style of the Menu proxy so that the entries expand and collapse when they are clicked. The example you provide of your employer's site has the behavior that I'm after (similar to what the TOC in a tripane project would be), but the Menu Skin Editor doesn't seem to offer a way to modify it, and there doesn't seem to be example Menu skins to download from Madcap.
    Thanks.
    Troy

    ReplyDelete
    Replies
    1. The expand/contract feature of the Menu proxy is actually part of the proxy configuration, I think? Aka, you can set that up within Flare in the proxy's settings.

      I'd go ahead and find that option, except for the fact that I'm no longer doing technical writing in favour of creating a whole lot of training videos and demos - I don't even have a Flare license on my PC anymore. But I'm 90% certain that this feature is built-in to the menu proxy or the TOC proxy or something.

      Delete