Tag Archives: JavaScript

Show and Hide with jQuery in HTML5 Output

MadCap Flare includes some show-and-hide controls for web-based outputs such as Togglers and Expanding Text. This blog has explored some alternatives for show-and-hide in the context of condition tags. Here is another option which uses jQuery to expand and collapse an element with a sliding animation.

Sliding show-and-hide actions are simple tasks with jQuery. Two such functions are slideUp() and slideDown(). Here is a function which uses both functions to show and hide an element given the element’s id attribute value.

You can add this script to many places in a Flare project. For simplicity in this example, here is an image of the script inserted into a topic and then edited.

insert-script

With the Attributes Window in Flare, you can set the value for an attribute of an element highlighted in the XML Editor. You can also edit the markup directly with the Text Editor. For this example the element to show and hide is given the value ‘show-hide’ for the id attribute.

id-attribute

The element to click is given the following value for the onclick attribute to call the JavaScript function. The value for id is passed to the function:

onclick-attribute

The final markup for the topic looks like this:

When the target is built and the output is opened, the click behavior looks like this:

expand-collapse

Other relevant concepts:

 

Hide Some Flare HTML5 Output Glossary Tab Entries

This example uses JavaScript, JSON, and jQuery.

In a response to a forum post, I suggested a rules-based approach to removing plural terms from the Glossary tab in Flare HTML5 output. The sample I provided tackled a few common English rules.

Rules-based Example to Remove Glossary Tab Entries with JavaScript

Rules are one way to approach the problem. Another way is to keep a list of items to remove or hide. What follows is another example which hides three terms on a Glossary tab when the function in the example fires. You can adjust the list of terms in the JSON object which holds the list of terms. You can also adjust when the function is called. In the example project, there is a toolbar button. But you can add an event listener to some other object to call the function if you do not want to be tied to the toolbar.

The sample project is configured as follows. There is a glossary with three glossary terms consisting of a plural term and a singular term: Child/Children, Apple/Apples, and Goose/Geese.

GlossaryEditor

There is a JSON object and a JavaScript function in the Toolbar Javascript.

ToolbarJavaScript

The skin has a custom toolbar button called HideEntries. When that button is clicked, hideEntries() from the Toolbar JavaScript is fired.

HTML5SkinEditorToolbar

HTML5SkinEditorStyles

The Glossary tab appears this way when initially viewed:

GlossaryTabBefore

After the HideEntries toolbar button (the blank one) is clicked, the three terms in the JSON object are removed from the list.

GlossaryTabAfter

A sample project is here: HideTerms.flprjzip

 

 

Quick Search Form for HTML5 Output

Here is a quick search form you can use on another page to open an HTML5 output search in the skin. To use it, change the value for uri (third line) to the URL for your Flare HTML5 help system’s main file. Then place the script and markup in the page markup where you want the form to appear on a web page.

search-form

search-form-with-term

search-results

Version Filters in HTML5 Output (persisting display instead of toggling)

In the previous post, the sample included a JavaScript which toggled the display attribute of elements between none and block depending on the value of a select element and the MadCap conditions applied to the elements.

But what if the display attribute wasn’t set to block in the first place? This second sample project includes a variation of the previous script which uses a custom data-* attribute to persist the original value of the display elements toggled. Instead of toggling between block and none, the original display attribute value is stored in a custom data* attribute and applied to the display element when the element is made visible again.

Section in W3C Working Draft: Embedding custom non-visible data with the data-* attributes

Why is this better? Not all elements start with a value of block for the display attribute and the default is inline anyhow. As an example, many menus implemented with CSS use a display value of inline to place the menus next to each other instead of underneath the previous. If you don’t care about that sort of thing, the original sample is sufficient. In other words if your granularity for tagging content by version doesn’t extend to elements which use display values of inline or something other than block, you can just toggle between block and none as the values for the display attribute.

Why is this controversial? The controversy surrounds the separation of markup and presentation. It also surrounds the idea of semantic misrepresentation. And the specification at one point indicated as much. Here are some links about that:

HTML Doctor: HTML5 Custom Data Attributes (data-*)

danwebb.net: Put that data-* attribute away, son…You might hurt someone

These are all valid concerns. Add to that, there is another way to indicate visibility. But given the situation of acting on markup in a help system after it has been built, isn’t this worth it? It definitely works. You can have filtering before publishing and in the output itself.

But it wouldn’t hurt to run the filtered content through a screen reader to see how the custom attribute and the filtering technique influences accessibility. My instinct is that it wouldn’t have a negative impact. But that is a subject for another post. This is an ongoing exploration.

sample project (version filter) 2

Version Filters in HTML5 Output

Keep the condition tags but skip the target settings.

Quick unpaid promotion! Attend MadWorld for my session and many others. Meet and learn from top technical communicators.

sample project

filter-in-flare-html5-topic

You can apply conditions to your Flare content and use those conditions to create a version filter in your Flare HTML5 output. The main ingredients are a select element and a little JavaScript. Here’s how.

We’ll start with a fresh project based on the Empty template which comes with Flare.

flare-with-empty-project

To keep it simple, we’ll use the Default condition tag set. But one of the nice things about having condition tag sets is there can be more than one. Since we aren’t going to touch the settings for these tags in the target, this is a situation when a separate set would make sense.

default-conditions

We can change the conditions to represent versions of a product. Periods are not allowed in the Condition Tag field. If you use periods or full stops (.) in version numbers you will have to find a different character for the tag. But you can still use the period in the text of the drop-down we will create in the topic.

new-conditions

Now we can create some content to which to apply the tags.

topic-no-conditions-or-filter

And apply the tags.

adding-condition-to-paragraph

Here is the topic in the XML Editor with the conditions applied:

topic-with-conditions

Now let’s look at those tags in the Text Editor.

topic-with-conditions-in-text-editor

Here is the first tagged paragraph. In the XML for the topic, the MadCap:conditions attribute holds the conditions. The condition is appended to the condition tag set name and a period symbol:

When there is more than one, the conditions are separated by commas.

File that in your memory. Now let’s add the UI for the filter. We can create a snippet to hold the filter for topic reuse. The snippet will use a select element, the element’s children, and some attributes. Here is the snippet in the Text Editor.

snippet-for-filter

There is an id attribute on the select element so the JavaScript can find the filter. The select element fires a JavaScript every time the the selection is changed. Here is the snippet in the topic:

snippet-in-topic

We can’t see the UI for the snippet from the Text Editor or the XML Editor. But we can see a preview when we add the snippet.

insert-snippet-for-filter

The JavaScript will look at the selected option and show or hide tagged elements based on the selection. Here is the JavaScript in Flare’s Text Editor:

show-hide-javascript

There are two functions. The first, getElementsWithAttribute, is used by the other function, showHideVersion, to get all of the elements in the topic with the data-mc-conditions attribute. Remember MadCap:conditions in the topic XML? That becomes data-mc-conditions in the HTML5 output topics.

The showHideVersion function looks for the select element and gets the selected option. Then it loops through all of the elements with data-mc-conditions and shows or hides the elements based on whether the elements include the selected condition.

The last line of the script ensures the script runs when the page initially loads.

We can reference the JavaScript in the master page. There is no default master page in the Empty template. We can base the new master page on the MasterPage.flmsp Factory Template. The script will go after the body element in the master page so we will add it through the Text Editor. Note the relative path to the file.

script-reference-in-master-page

Let’s not forget to add the master page to the target.

adding-master-page-to-target

At this point we are ready to build. Here again is how the output looks. You can select a version and only content tagged with that version appears.

filter-in-flare-html5-topic-drop-down-not-open

 

filter-in-flare-html5-topic

Now you can filter on a single condition in a topic from the published output. In this example and sample, the content must be tagged to appear. But you don’t have to limit yourself to that behavior with your JavaScript. What kind of filter behavior would you expect to see in a version filter? Let me know in the comments.

sample project

Update: There is a follow-up post and sample which persists the original display value instead of toggling between none and block.