Display page labels on Viewport pages

A empty string search with this recipe seems to be broken currently. We are looking into this to update the recipe.

This page will show you how to display page labels in the Viewport view. The instructions are focusing on adding it to the Web Help theme, but the general approach should work with any theme.

Creating include-labels.vm

The easiest to manage way to add a component to the theme is by creating an own .VM file for it. In the Web Help theme, template includes are store in the include directory. 

Navigate to that directory and create a file named "include-labels.vm". Paste the following code into it.

<div class="labels-content" style="margin: 25px;">
  <ul class="label-list label-list-right">
    #foreach ($label in $page.labels) 
    <li class="aui-label"><a href="$viewport.link/search?q=&l=$label.name&max=15"> $label.name </a></li>
    #end
  </ul>
</div>

The code above displays all of the page labels in the same style they would be displayed in Confluence.

The Labeled content screen that labels in Confluence link to isn't available in Viewport, as only pages and blog posts have Viewport views. Thus, the code above leads to a Viewport search result page that displays all pages in the space with the clicked label.

Referencing the created file in the page

To now make the code above run whenever one is viewing a page in the Viewport theme, the template needs to be called from the page template. 

You can place the reference anywhere you like, but for this recipe, we'll place it right above the "Next article >" button in the bottom right of the Viewport page. To achieve that, navigate to the include-content.vm and locate the closing tag </article> (should be on line 20). Right below it but above the navigational button starting with <nav id="ht-post-nav"> paste the reference to your newly created .VM file:

</article>
$include.template("/include/include-labels.vm")
<nav id="ht-post-nav">

Optional: Labels list and Popular labels macros

The Labels list and Popular labels work well visually within the Web Help theme, but their links are pointing to the out-of-space Confluence UI by default. While the more stable approach is to create a macro override, the include-labels.vm from above can be altered slightly to make the links behave in a similar way as the page label links:

<div class="labels-content" style="margin: 25px;">
  <ul class="label-list label-list-right">
    #foreach ($label in $page.labels) 
    <li class="aui-label"><a href="$viewport.link/search?q=&l=$label.name&max=15"> $label.name </a></li>
    #end
  </ul>
</div>
<script>
var viewportLink = '$viewport.link';
var listedLabels = $("div.labelsAlphaList[data-macro-name='sp-listlabels']").find("li > a");
if (listedLabels.length > 0){
    listedLabels.each(function(){
        $(this).attr("href",viewportLink+"/search?q=&l="+$(this).text());
    });
};
var popularLabels = $("li.popularlabel > a");
if (popularLabels.length > 0){
    popularLabels.each(function(){
        $(this).attr("href",viewportLink+"/search?q=&l="+$(this).text());
    });
};
  </script>

As the search page the labels are linking to is limited to the current space, the macro scopes should be chosen accordingly.

This concludes the implementation and the recipe. Please note that this has been done with an unaltered Web Help theme. If your theme differs, you might have to add your own styling to it.