Widget Builder: Building a Contextually Based Pagelist

Thu Apr 5, 2018

Technical Skills: Intermediate to Advanced Widget Developer

This post describes how to build a contextually based pagelist widget using the Velocity Templating language and the Auto Widget Content Finder utility introduced in the previous Widget Builder blog post: Building a Related Content Widget Builder Widget.


Identifying the problem

Let's say you wanted to build a page list for additional navigation based on the context of where the current page is in the site, but the percussion page autolist widget and navigation widgets aren't giving you quite what you need. 

In this example we have three "Collections" and each collection directory has a number of "Item" pages. We want a widget that populates a dropdown menu with the other item pages within the Collection folder that our current page is in. 

Easy, right? 

With the Auto Widget Content Finder, it actually is. 


Setting up the parameters

In the custom widget builder we first need to acquire the folder location of the current page in order to include it in our Auto Widget Content Finder query.

The variable $perc.page allows us to access a large number of properties of the current page, including the path of the current page's folder with the property folderPaths

We can set it using the command:

#set ($parentFolderPath = $perc.page.folderPaths.get(0))## 

Note: Even though we only have one path stored, the $perc.page object stores the value in an array so we need to use the "0" index to get the first item which is our path.

Next we set our system query to look for the   sys_contentid and   sys_folderid of items of type   Page that are found in the folderpath we stored earlier:

#set($query = "select rx:sys_contentid, rx:sys_folderid from rx:percPage where jcr:path like '$parentFolderPath%' ") ##

We then set up our  $params variable and add our max results value ('-1' to search for all) and add our query string. 

#set($params=$rx.string.stringToMap(null)) ##

#set($dummy=$params.put('max_results', -1)) ##

#set($dummy=$params.put('query', $query)) ##

We choose the Auto Widget Content Finder using:

#set($finderName="Java/global/percussion/widgetcontentfinder/perc_AutoWidgetContentFinder") ##

Then we store the returned results in a variable named  $relresult.





Outputting our results

Now that we have our pages collected in $relresults we can use velocity's #foreach loop to cycle through them to grab the page properties we need and output them onto the page.

In this example we are making a dropdown menu filled with the page name and link for each of the other pages in our Collection Folder. So we'll set up our HTML in the Widget Builder Display field to create the structure we need with our wrapper div, a menu title, and some javascript for our form.

<script type="text/javascript">

function displayMenu(s) {

<div class="wrapper">
    <div class="dropdown-menu">
        <div class="row">
            <div class="large-12 columns">
                <span class="bold">$menuTitle</span>
                <select onchange="displayMenu(this);">

Then we begin the #foreach loop and get our three variables: pagename, pagelink, and linkTitle:

#foreach($result in $relresults)##

#set($pagelink=$tools.esc.html($rx.pageutils.itemLink($perc.linkContext, $result)))##
#set($linkTitle=$rx.pageutils.html($result.node,"resource_link_title,sys_title", "-no-title-"))##

Next we test to see if our current page $perc.page.name matches the pagename of our result and we can add our form option value and mark it "selected" so whenever you navigate to a page, the current page will be the default selected value displaying in our drop down. 

After that we add the rest of the results in our form and fill the values of the linkTitle and pagelink 

#if ($perc.page.name == $pagename)##
     <option value="$pagelink" selected>$!{linkTitle}</option>
     <option value="$pagelink">$!{linkTitle}</option>

#end## end foreach loop

Now we can wrap up the HTML, save our widget and deploy!


Since we want the widget dropdown to populate based on our page context we add the widget to our template that is applied to all of our "Item" pages and enter the widget title at the template level. 

When we preview any of our Item pages we can now see that the dropdown contents changes to show the pages in our current directory. 

In the screenshots below I added the Title widget a Navigation widget that show our Collections folder and our custom dropdown widget below it. You can see the selected dropdown value adjusts based on the page that you are currently on.


Pretty neat, right!?


You can download this example code here and customize it for your own site.

Of course, we're not limited to a dropdown form, so we could easily output the results into a list or any other HTML structure you'd like and make it all pretty using Casey's great CSS tips!

In addition, there are many other properties we can read from the page results that come back from the Auto Widget Content Finder. We can grab the page summary, for example, or categories, or tags, and many other properties which we'll cover in future Widget Builder blog posts. 

Piotr Butkiewicz
Piotr Butkiewicz
Web Consultant | Percussion Software