Conditional content based on tags

Here we describe how to display one of any number of snippets based on the tags an article has. Some comfort playing with code is required, but no coding knowledge is needed - we will give you everything you need, just follow these steps.

You may have alerts or other content that you only want displayed in certain circumstances. For example, maybe your articles fall into various plan or privacy levels that your customer service employees should be aware of when advising a customer. The uses for this tutorial are versatile and varied.

For the purposes of this article, let's role-play - my knowledge base is for a customer service team for a product that has three plan levels: Basic, Pro and Extreme. Each of the articles in my knowledge base is only relevant to one of these plan levels.

Note: Once you have completed these setup steps, the display of these snippets depends on the tags an article has. Instead of using tags, you could just manually insert the snippet that is relevant to the article each time. This setup is only useful if you already do or plan to use tags to identify articles this way. Also, the use of tags means articles can be bulk edited, and the tags are visible in search results too.

The overall steps to set this up are:

  1. Create the conditional content you want to display in individual snippets.
  2. Create tags for each snippet.
  3. Edit your Article HTML template to include all your snippet merge codes.
  4. Add a script that will look at a given article's tags and determine which snippet's content to display.

Each step is explained in detail below.

Create your conditional content & tags

Before we do anything else, we should prepare our conditional content and create our tags. 

We are using three tags & snippets here, but you can use as many as you like.
  1. Start by creating your conditional content, each one in its own snippet. If you're new to creating snippets, check out Creating a snippet.
    • Alert boxes work really well for this, but you can include whatever content you like - the snippet WYSIWYG editor has all the same features as our article editor.
    • You could also use topic articles for your conditional content, if that suits your use case better.
  2. Once your snippets are created, copy each snippet's merge code to a text editor of your choice. We'll need them later.
  3. Now create and add your tags to your articles. In this example, I have three tags for my three plan levels - "Basic Plan", "Pro Plan" and "Extreme Plan". You can learn more about adding and managing tags here.
    • Each article should only have one of these tags. If it has more than one, the last tag in the list is the only one that will be used.
    • The article may have other tags that aren't used for conditional content. They won't impact how all of this works.

Add code to your article HTML template

Now that you have your content and tags ready, we need to add the snippets to our article HTML template. This helps pull in those pieces of content into all your articles so that the tags and the script will select which of the snippets to display in each article.

To do so:

  1. Go to Settings > Style.
  2. Below the preview pane, be sure Custom HTML is selected.
  3. In the Custom HTML dropdown, select Article.
  4. Right near the top, look for <div class="hg-article-header">. Copy the code below and paste it in just below that:
    <div class="article-tags">[template("article-tag-names")]</div>

  5. A little further down, look for [article("body")]. Copy the code below and paste it in directly below that:
    <div class="tag-conditional-content-container invisible">
      {{snippet.conditionalContentScript}}
      <div class="tag-conditional-content invisible conditional-content-level-1">MERGE CODE GOES HERE</div>
    </div>
  6. Now add and modify a line for each chunk of conditional content you created earlier:
    1. Copy the line with MERGE CODE GOES HERE and paste as many below as needed (we needed three so we copied the first one and pasted two more).
    2. In the middle of each line you'll see conditional-content-level-1 - on each line, change the number at the end to 2, 3 etc.
    3. Replace MERGE CODE GOES HERE with each of your snippet merge codes.
      The end result should look something like this:
  7. Take note of which snippet you put at each conditional-content-level. You'll need it later.
  8. Now select the Custom CSS tab.
  9. Copy the code below and paste it anywhere in your Custom CSS:
    /* Tag-based conditional content */
    .tag-conditional-content-container {
      opacity: 100;
      transition: all 0.5s;
    }
    .tag-conditional-content-container.invisible {
      opacity: 0;
    }
    .tag-conditional-content.invisible {
      display: none;
    }
    .article-tags {
      display: none;
    }
  10. Be sure to Save your changes once you're done.

Create your script

We have our content, our tags, and all the HTML and CSS framework we need. Now we just need a script to determine what to do with all of it.

  1. Go to Library > Snippets.
  2. Create a new snippet.
  3. Give your snippet a name, like Conditional Content Script.
  4. Switch from WYSIWYG Editor to Code Editor.
  5. Copy the code below and paste it into the Code Editor.
    <script>
      $(function() {
    
        /** Modify the tag names below to match your conditional content. You can identify which is which by heading to Settings -> Style, Custom HTML tab, Article, and scrolling down to the conditional content where these snippet merge codes are **/
       
        var contentLevelDefs = [{
          'class': 'conditional-content-level-1',
          'tagName': 'Basic Plan'
        },{
          'class': 'conditional-content-level-2',
          'tagName': 'Pro Plan'
        },{
          'class': 'conditional-content-level-3',
          'tagName': 'Extreme Plan'
        }];
    
        /**** Leave everything below here as is ****/
        var def; // Prepare an empty variable to store the tag definition we need
        var tags = $('.article-tags').text().split(','); // Convert the tag names into an array
        // For each tag in the array we just created, find the tag name that matches one of our definitions.
        // NB If there are multiple tag names that match definitions, the last one to be matched will be used
        tags.forEach(function(tag) {
          var matches = contentLevelDefs.filter(function(o) { return o['tagName'] === tag });
    	  if (matches.length > 0) {
    	    def = matches[0];
    	  }
        });
        // If we matched a definition...
        if (def) {
          // Remove the invisible class from the matched element
          $('.'+def.class).removeClass('invisible');
          // And display the entire container
          $('.tag-conditional-content-container').removeClass('invisible');
        } else {
          // If we didn;t find a match, send an error to the console to help diagnose why this may have happened
          console.log("No conditional content tag definition found for this article's tags");
          console.log('Article tags:', tags);
          console.log('Content level definitions:', contentLevelDefs);
        }
    
      });
    </script>
  6. Modify the "contentLevelDefs" Defs stands for definitions - these create a connection between the HTML and snippet merge codes we pasted in earlier with your tag names . 
    • 'class': this helps the script identify which line of HTML (and in turn, which snippet merge code) we are talking about. You shouldn't need to change this, but you can use it to identify each of the lines by looking at your HTML:
    • 'tagName': update this with the name of the tag that you want to associate with that line of HTML code - if the article has this tag, that line of code (and the snippet it contains) will be displayed. Be sure you've captured the tag name exactly as it appears in your tag library--spelling, capitalization, and so forth need to be an exact match.
    • Be sure to keep the class and tagName in 'single quotation marks'.
    • If you need to add another definition because you have more than three chances of conditional content, ensure formatting remains consistent. Each definition should be separated by a comma and it should look something like this:
      {
        'class': 'class-name-from-your-html',
        'tagName': 'Tag Name'
      }
  7. Save your snippet.
  8. Copy the snippet's merge code.
  9. Go to Settings > Style.
  10. Below the preview pane, be sure Custom HTML is selected.
  11. In the Custom HTML dropdown, select Article.
  12. Paste your snippet merge code in anywhere in the Article Custom HTML edit pane.
  13. Save your changes.

You should now have your content display based on what tag is present on the article! If your article is showing the wrong content, or none at all, contact us and we'll take a look.