Filters in online documentation

Most authoring tools for technical documentation come with a function for conditional text. However, this usually only lets you map static scenarios.

With CSS, you can also react to conditions that become known or arise only at runtime – for example, as a result of a user decision or depending on the device used for display.

Example 1: Content filtered by users

Filtering the content displayed in an online documentation at runtime at the push of a button can be implemented with comparatively little effort with most authoring tools. It can be used, for example, to switch between a complete documentation and a shortened version.

The solution presented here even works with more than two categories if needed. For example, you could filter your content by industry, by programming language, by audience, by version, or by any other criteria. The goal always is to save user from having to read things that are irrelevant to them.

First section

I am essential information that all users need to know.

I am additional information for those interested in the details. Don’t you care? Then ignore me. Why should you read more than you need?

Second section

I am some other essential information. Don’t miss me. I am key.

I am some other additional information that you can most likely live without. You can skip me for now if you don’t have enough time if or you are a lit lazy. Relax. Take it easy. Have a good time. Don't rush into work.

Implementation for example 1

The solution presented here is based in essence on a tutorial from W3Schools.

Step 1: Add the following CSS code to the CSS file used by your online documentation or to the head section of your page template:


.filterDiv {
  display: none;
}
.show {
  display: block;
}
.btn {
  border: none;
  outline: none;
  padding: 12px 16px;
  background-color: #f1f1f1;
  cursor: pointer;
}
.btn:hover {
  background-color: #ddd;
}
.btn.active {
  background-color: #666;
  color: white;
}

Step 2: Insert the following HTML snippet at the place in your topic where you want the buttons to appear that toggle the filters on and off:


<div id="filterBtnContainer">
 <button class="btn active" onclick="filterSelection('all')">Full read</button>
 <button class="btn" onclick="filterSelection('quickread')">Quick read</button>
</div>

Step 3: Place each section of the topic that you want to be hideable between the following two HTML snippets. The first of these HTML snippets also contains the name of the filter group to which the respective section belongs. In the presented example, there is only one filter group with the name fullread.


<div class="filterDiv fullread">


</div>

Note: In this example, we are not filtering for the “fullread” group at all with the buttons, but for a non-existing “quickread” group. Since the sections marked as “fullread” do not belong to the “quickread” group, the contents of the “fullread” group will thus be hidden.

Step 4: Finally, add the following JavaScript code at the end of the topic or at the end of the body section of your page template:


<script>
filterSelection("all")
function filterSelection(c) {
 var x, i;
 x = document.getElementsByClassName("filterDiv");
 if (c == "all") c = "";
 for (i = 0; i < x.length; i++) {
  filterRemoveClass(x[i], "show");
  if (x[i].className.indexOf(c) > -1) filterAddClass(x[i], "show");
 }
}
function filterAddClass(element, name) {
 var i, arr1, arr2;
 arr1 = element.className.split(" ");
 arr2 = name.split(" ");
 for (i = 0; i < arr2.length; i++) {
  if (arr1.indexOf(arr2[i]) == -1) {
   element.className += " " + arr2[i];
  }
 }
}
function filterRemoveClass(element, name) {
 var i, arr1, arr2;
 arr1 = element.className.split(" ");
 arr2 = name.split(" ");
 for (i = 0; i < arr2.length; i++) {
  while (arr1.indexOf(arr2[i]) > -1) {
   arr1.splice(arr1.indexOf(arr2[i]), 1);
  }
 }
 element.className = arr1.join(" ");
}
var btnContainer = document.getElementById("filterBtnContainer");
var btns = btnContainer.getElementsByClassName("btn");
for (var i = 0; i < btns.length; i++) {
 btns[i].addEventListener("click", function() {
  var current = document.getElementsByClassName("active");
  current[0].className = current[0].className.replace(" active", "");
  this.className += " active";
 });
}
</script>

Example 2: Content depending on the device and display used

Sometimes it can be useful to hide or swap out certain information, depending on the device and display. For example, you could:

▪omit or abbreviate certain content if a user only has a small screen for reading the documentation

▪present different information on a mobile device than on a desktop device

▪provide other instructions on a device that has a touch screen than on a device that uses a keyboard and a mouse

Things like these can be implemented with the following queries. Go ahead and try it both on a computer and on a cell phone:

Only on large screens

The following image and the associated text appear only if the display is at least 500 pixels wide.

Here I am.

Only on small screens

The following image and associated text appear only if the display is no wider than 500 pixels.

Here I am.

Only on devices that have a mouse pointer

The following image and associated text only appear on devices on which a mouse pointer is available.

Here I am.

Only on devices that do not have a mouse pointer (touchscreen)

The following image and associated text appear only on devices where no mouse pointer is available – for example, on a touchscreen.

Here I am.

Implementation for example 2

Step 1: Add the following CSS code to the CSS file used by your online documentation or to the head section of your page template:


@media not (min-width: 500px) {
  .only-if-large-screen {display: none;}
}
@media not (max-width: 500px) {
  .only-if-small-screen {display: none;}
}
@media (hover: none) and (pointer: coarse) {
  .only-if-pointer {display: none;}
}
@media not ((hover: none) and (pointer: coarse)) {
  .only-if-no-pointer {display: none;}  
}

Step 2: Put each conditional section between two HTML snippets.

> For content that is to be displayed only on large screens:


<div class="only-if-large-screen">


</div>

> For content that is to be displayed only on small screens:


<div class="only-if-small-screen">


</div>

> For content that is to be displayed only on devices that have a mouse pointer:


<div class="only-if-pointer">


</div>

> For content that is to be displayed only on devices that do not have a mouse pointer (touchscreens):


<div class="only-if-no-pointer">


</div>

___

Did you benefit from this information?

In return, please link to this page, mention the page on social media, or buy one of my books.

Thank you!