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.
A screenshot showing newly created project  in madcap flare using the Empty template.

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.
An image showing conditional tag set in madcap flare to create version filters.

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.
applying conditions to create version filters in madcap flare

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.
A screenshot showing a generic class created and style display:none applied in madcap Flare stylesheet editor to create version filters.

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

13 thoughts on “How to create version filters in Madcap Flare

  1. This functionality is exactly what I need. The version doesn’t persist between pages. Each page defaults to version 3 rather than the option selected by the user. I’m using Flare 2021 r2. I appreciate the time you took to provide a thorough explanation. I am not familiar with JS, so I’m sure someone more knowledgeable would be able to figure out the issue.

    1. Hello Lori, Thank you for reading and trying out the version filters!
      As correctly pointed out by Dave Lee, there was an error in the JS that I wrote. I have updated the post with the correct JS code, you can try now and let me know if you still face any issue.

  2. Good example, but I think you’ve missed out one important part. Nothing in your HTML or script actually calls the myFunction() function, so it is never run. But I could get it working by adding this line to the top of the script:

    myFunction();

    1. Sorry, I do not have any site that has this implemented. This was just a proof of concept that I worked on. Since, it was interesting and can be helpful for someone in need, I thought it will be worth sharing here.

  3. Thank you for this guide. I’ve implemented this and the version selection works, but it does not apply the default selection on page load and it doesn’t preserve the selection when the page is refreshed. Any ideas where to start troubleshooting this?

    1. Sorry, there was one minor error in the JS code that I wrote. Because of this error the version filter was not applying the default value and was not saving the selected filter. I have updated this page with the corrected JS code and its working for me. You should try once again and if you still find any issue, feel free to comment again. I will be happy to help you.

  4. Hello, I know this some what of an old article now but I just came across it. I got it to work but if I swap to say version 3 there is a big gap on the topic where version 1 and 2 information is. Is there anyway round this?

    1. Hello Robin,
      I would suggest you check how you have applied the Conditions (conditional tags) in Madcap Flare. One of the reasons, I could think for your issues is that you have applied the conditions on the text and not the entire paragraphs. So, when you switch to version 3, there are empty paragraphs left on the page.

  5. Hi, thanks in advance for your help. I have tried using this method of versioning and when I open the newly generated html file, I can see the dropdown menu but the conditional text does not change no matter what I select in the dropdown menu. I have three test paragraphs, each of them has a different condition set on it and all three are not being displayed at all when I choose different versions in the dropdown menu. What could be the problem here?

  6. Is this possible if we have different source files and the content is posted on different locations. Is there a limitation that all content has to be there in a single source file with proper conditional texting for this to work.

    1. I am not sure, if I get your question correctly. If the content is not in a single source file, why would you need a dynamic filter?
      This version filter is simply a show and hide button, where the content for the selected version is shown and rest all are hidden. However, all the content is available in the same HTML page. If you are keeping everything separately, then you do not need a filter. You can simple create a hyperlink/button, which will redirect the user to the right content.

Leave a Reply

Your email address will not be published. Required fields are marked *