This guest post was written by Yaroslava Kachan. Yaroslava has been working as a tech writer for over 5 years. She is a co-founder of the tech writers community in Ukraine, organizer of workshops, lecturer, and author of articles on technical writing.
What Task Do We Solve?
Among other products, my company KMD develops an add-in for Microsoft Outlook. Outlook is available as a desktop solution and as a web solution so that users can access it in a browser. While 90% of the features and UI elements for the desktop and web solutions are aligned, about 10% still differ.
Our users can use both Outlook on the desktop or on the web depending on their taste, and we never know what a specific user prefers. The link to our documentation is hardcoded in our add-in, so I cannot create two different versions of online help for desktop and web. Constantly repeating the phrase: “If you use the desktop Outlook, do the following…. If you use the web Outlook, do the following…” this is not an elegant solution. That was my challenge.
I was looking for an elegant solution and found the article in this blog called How to Implement Live Filtering Into Your MadCap Flare Project by Daniel McLeod. I contacted Daniel to discuss the possibility of buying his scripts. However, we discovered that his solution is not universal and it is applicable only to his documentation.
About Global Live Filtering and Topic Live Filtering
Live filtering is a functionality that makes it possible to switch between different modifications of a page. Moreover, this solution can be applied to the project level (Global live filtering) or on the topic level (Topic live filtering).
Here is an example of the Global and Topic live filtering UI:
- When you apply Global live filtering, buttons will appear on the toolbar and they will affect the entire guide.
- When you apply Topic live filtering, buttons will appear in the topic and they will affect the topic only.
This diagram describes the default logic of Live filtering:
When a user opens documentation for the first time, the Desktop button is clicked by default and the user sees the documentation for desktop. If the user clicks the Web button, the system memorizes this choice and the user starts seeing the documentation for web. If the user closes the browser and then opens it later, the latest choice is stored and the user sees the documentation for the web version.
As you see, you can set the default value. In our case, it is Desktop.
Important note: While Topic live filtering applies to all three skin types (Tripane, Top navigation, and Side navigation), Global live filtering applies to the Tripane skin only.
You must also configure:
- A Skin file
- A CSS file
- Create a new skin based on the HTML5 Component – Topic Toolbar template:
- Create two buttons. In my example, I named the buttons Desktop and Web and used the blue arrow to move them to the Selected pane:
CSS and Classes
- While not mandatory, I recommend having a separate stylesheet to make your solution more flexible. Let’s name it Live_filtering.css.
- Reference Live_filtering.css in your main stylesheet:
- In the p tag, right-click, choose New Selector, and create two classes: Desktop and Web:
- Create content for desktop and web:
- Mark content for desktop by using class .Desktop:
Repeat the same for web by using class .Web. To make the procedure quicker, you can also group p tags together and wrap them in a div tag. In this example, I have a div class called div.Web, and using the Group button in the Home ribbon, I can quickly wrap both p tags in this div.
- On the Insert tab, insert a Topic Toolbar Proxy, which will act as a container for the skin component created earlier:
The skin will be inserted into the place where you have set your cursor. In other words, you can place buttons at any place in your topic.
- Save the changes and build the project:
Moreover, you can add different Topic live filtering skins to the same topic. As an alternative approach, you can try to use the proxy in a masterpage, to make it easier to apply to all topics.
In the course, I also describe step-by-step procedures of how to configure Code formatting and the Copy-to-clipboard button. These solutions were not invented by me, but I have optimized them as much as possible, so after the configuration, it will take just a few seconds to apply each of them.
I provide a 25% discount for readers of this blog. To get the coupon, please contact me via email: firstname.lastname@example.org.
Thank you very much for reading!