How to create version filters in Madcap Flare

Version filters or filter drop-down list, is used to dynamically change the content as per the users’s selection.

Do you have online help that serves multiple types of audiences? Do you want to give your user the freedom to choose the version of the help?
If you have these questions in your mind and thinking how to achieve it in Madcap Flare then, this post is for you. In this post, I will provide you a step-by-step guide to create a dropdown filter in Madcap Flare.
I am using Condition tags, a little bit of Javascript, and Windows session storage property of HTML5 output.

Don’t worry, if you do not know Javascript, I will try my best to explain and make it simple in this post. After reading this post, I believe you would not only be able to create the same dropdown list I created, but you could modify it according to your needs.

I will be honest, this hack is an improved version of Version Filters in HTML5 Output post written by Thomas Tregner.

Create a new project in madcap Flare

Let’s get started by creating a new project using the Empty template of FLARE and an HTML5 target.

1. In the madcap Flare window, go to File > New Project.
2. Enter the project name, select the Project Folder, and click Next.
3. In the New from template column, select the Empty template, and click Next.
4. From the Available Targets, select HTML5 as your target and click Finish.

Create conditions in a conditional tag set

In the madcap flare, a conditional tag set saves conditions for your project. You can have multiple conditional tag sets in a project and one conditional tag set can have multiple conditions. You can use conditions to generate show/hide content and generate multiple outputs in one project. However, in this post, we will use conditions for the user to show hide content.

1. To create a new conditional tag set, go to Project > New > Condition Tag Set. Alternatively, in the Project Organizer, right-click on the Conditional Text folder and select the Add Condition Tag Set. For this post, we will use the Default conditional tag set that came with the factory templates.
2. Double-click a conditional tag set.
3. There will be a few Conditional tags already available, rename them as the option you want to give to your user. I have renamed them as follows:
   • Version 1
   • Version 2
   • Version 3
4. Save the file.

Apply conditions to your content

You can apply conditions to topics, images, stylesheet, glossary, skin, target files, entire paragraphs, and text within paragraphs. table rows and columns, table of contents (TOC) entries, glossary terms, index keyword markers, and more.

Unfortunately, this trick only works on conditions applied at entire paragraphs, text within paragraphs, and table rows and columns.

1. To apply a condition tag to a paragraph, the quickest way is, right-click on the paragraph block, select Conditions, and on the Condition Tags dialog box, select the condition.
2. To apply a condition to the text within a paragraph, select the text, right-click on the selected text, select Conditions, and on the Condition Tags dialog box, select the condition.
3. Don’t forget to save it.

Add a generic class in the stylesheet

To hide specific content from our HTML5 output, we need to create a generic style, which we will use later. To add a generic style, do the following steps:

1. Double-click the default style sheet to open it in the madcap flare stylesheet editor.
2. Click Add Selector.
3. From the HTML element dropdown list, select Generic.
4. In the Class Name box, enter .hidden1, and click OK to add a new class.
5. In the stylesheet editor, ensure that Show: All Properties is selected.
6. For the newly created .hidden1 class, in the block property group, in the display box, enter none.

Create a dropdown menu for filters

We will add the drop-down list on the master page, so that it appears on every page. This is the drop-down list that will work as our version filters in the final output

1. Double-click the master page to open it.
2. Click the text editor as we need to put it in some HTML code.
3. In the master page, above the body proxy, copy and paste the below code, and save the master page file.

<select id="version-select" onchange="showHideVersion()">
    <option value="Default.Version 1">Version 1</option>
    <option value="Default.Version 2">Version 2</option>
    <option value="Default.Version 3">Version 3</option>
</select>

Let us understand what are we doing with this HTML code.
We are creating a drop-down list with an ID “version-select” and having three options. The drop-down list will call a function whenever the user changes select an option. “Select” is the HTML element for a drop-down list. Whenever user select a version, “onchange” property triggers function “showHideVersion()”.

We have three options for user Version 1, Version 2, and Version 3. These options have a value associated which is stored in the “value” property of the “option” element.

You may wonder, why “Default.Version 2”, “Default.Version 2”, and “Default.Version 3” and not anything else.
To find the answer to this question, take a look at the topic where we had applied the conditional tags to the paragraph blocks in a text editor. You will find that when we applied the conditional tag to a paragraph, madcap Flare changes its attributes. Flare adds “MadCap:conditions” attribute to the element. I am using the same values as our options.

If you are using a conditional tag set other than the Default tag set then, these values will change. Use the same value that you see in your text editor.

Add a Javascript into a madcap Flare project to create version filters

Adding a Javascript into a madcap Flare project is simple. You can add a Javascript code in madcap Flare but you cannot create a Javascript file in Flare. You can create a separate Javascript file using a text editor, save it with a .js extension, and then link it into your project. You can add the Javascript code or link a Javascript file into a topic, a snippet, or a master page. We will add our javascript code directly to our master page. This code will filter the content based on the value selected by user from our version filters drop-down list.

1. Double-click on the master page in which we added our dropdown list.
2. Switch to XML editor.
3. Add a paragraph at the end of the page, go to Insert ribbon, and select Script.
4. In the Insert Script dialog box, from the Language dropdown list, select text/javascript.
5. In the Script Code box, copy and past the following code, and then click OK.

myFunction()
function getElementsWithAttribute(attr) {
    var elementsWithAttribute = [];
    var elements = document.body.getElementsByTagName('*');
    for (var i = 0; i < elements.length; i++) {
        if (elements[i].getAttribute(attr)) {
            elementsWithAttribute.push(elements[i]);
        }
    }
    return elementsWithAttribute;
}
function showHideVersion() {
    var elements = getElementsWithAttribute('data-mc-conditions');
    var e = document.getElementById('version-select');
    var selectedVersion = e.options[e.selectedIndex].value;
    for (var i = 0; i < elements.length; i++) {
        if (elements[i].getAttribute('data-mc-conditions').indexOf(selectedVersion) > -1) {
            elements[i].classList.remove("hidden1");
            localStorage.id = e.options[e.selectedIndex].value;
        } else {
            elements[i].classList.add("hidden1");
        }
    }
}
function myFunction() {
    var elements = getElementsWithAttribute('data-mc-conditions');
    var locals = localStorage.getItem('id');
    if (locals == null) {
        localStorage.id = "Default.Version 3";
        locals = localStorage.getItem('id');
        for (var i = 0; i < elements.length; i++) {
            if (elements[i].getAttribute('data-mc-conditions').indexOf(locals) > -1) {
                elements[i].classList.remove("hidden1");
                document.getElementById('version-select').value = locals;
            } else {
                elements[i].classList.add("hidden1");
            }
        }
    } else {
        for (var i = 0; i < elements.length; i++) {
            if (elements[i].getAttribute('data-mc-conditions').indexOf(locals) > -1) {
                elements[i].classList.remove("hidden1");
                document.getElementById('version-select').value = locals;
            } else {
                elements[i].classList.add("hidden1");
            }
        }
    }
}

The above code has three functions. Let us understand what are we doing in this code step-by-step.

The first function – getElementsWithAttribute

The function is used in the second function “showHideVersion” which does the main job.

The second function – showHideVersion

We call this function whenever the user changes the value of our dropdown list. Let us see what each line of code in the function showHideVersion does.

var elements = getElementsWithAttribute('data-mc-conditions');

This statement creates a variable (variable is used to store values) named “elements” and calls the first function “getElementsWithAttribute”. It will find all the elements on your page having the “data-mc-conditions” attribute and store it in the “elements” variable. Remember when we look at a topic with conditions applied. The madcap Flare added “MadCap:conditions” attribute to our paragraph element. When we generate an HTML 5 output, the “MadCap:conditions” attribute changes to “data-mc-conditions”.

var e = document.getElementById('version-select');

This statement creates a variable “e” and stores the element having ID “version-select”. Now, if you remember we gave this ID to our dropdown list.

var selectedVersion = e.options[e.selectedIndex].value;

This statement creates a variable “selectedVersion” and stores the value of the selected option in the dropdown list with variable “e” which we created in the above statement and stored our dropdown list.

for (var i = 0; i < elements.length; i++)

This is a for loop that will iterate the below statements to the number of times we have the elements with the “data-mc-conditions” attribute.

if (elements[i].getAttribute('data-mc-conditions').indexOf(selectedVersion) > -1 )

This is a condition that verifies if the element with the data-mc-conditions attribute has the same value as the option selected by the user. For example, from the dropdown list, we created, if a user selects Version 2. Then, this statement will check all the elements that have an attribute “data-mc-conditions = “Default.Version 2″”.
Because of this reason, when we created our dropdown list, we matched the value in the “value” property of options to the value of “MadCap:conditions” attribute in paragraphs.

elements[i].classList.remove("hidden1");

For all those elements that match with the above condition, this statement removes our “.hidden1” class and brings back to their default state. This will show the matched element to a user.

localStorage.id = e.options[e.selectedIndex].value;

This statement is to store the user selection in users browser so that when a user moves from one page to another, the user sees the content he chose.

else {             elements[i].classList.add("hidden1");         }

For all those elements that do not match with the above condition, this statement adds a class “hidden1”. We have created this class with a style “display: none;”. This will hide the unmatched element from the user.

The third function – myFunction

This function is called whenever a page loads. This function is to check the value we stored in the user’s browser. The first statement is the same as we used in the second function.

var locals = localStorage.getItem('id');

This statement creates a variable with the name “locals”, gets the user’s selection from the user’s browser, and stores the value in the variable.

if (locals == null)

This is to check if the user is visiting our help for the first time. We are saving our user’s selection value and if a user is visiting for the first time, there are no values. In this case, the next statement does our job.

localStorage.id = "Default.Version 3";

This statement stores a value in the user’s browser storage. This is the same as setting a default value. For now, I am selecting Version 3.0 as default as this is the latest version. You can modify it according to your use case.
Rest all the statements are doing the same job as to show and hide content as we did in our second function. The only difference is that instead of looking at the user’s selection we are checking the value stored in the user’s browser.

Generate the output and test it

The last step of this trick is to open the target file, on the Advanced tab, and from the Master Page dropdown list, select the created master page. Now, we are ready to build our target and test it.

I hope this post helps you to build an HTML5 output with version filters. If there is anything I missed, please feel free to comment on this post.

---

Also See

How to make money online without investment.

Best Wattage For LED Nail Lamp