Several use cases for Page Properties / Report, illustrated

[#1]

I first used the Page Properties macros to post a backlog of meeting recordings. I needed to sort the list by event date, not created or modified date, and the Page Properties and Page Properties Report macros (PP and PPR for convenience) enabled that. Since then, learning this macro combination has paid off in several ways.

The PP and PPR macro combo is one of the few out-of-the-box ways to include information from one wiki page on another wiki page. The PPR macro enables sorting of any PP column, and page labels or location enable filtering. There’s surprising power and flexibility for retrieving page content.

Here are some of our use cases, followed by a display tweak I use to suppress the page title column. If you have another creative use for PP and PPR, I’d love to hear about it!

Listing events

Formatting the date as YYYY-MM-DD enables listing future or recent events at the top of the list. Here Event date is in descending order. I’ll demonstrate in more detail in an upcoming post, including a hack to hide the Title column and other report elements for a more minimal presentation.

Showing key elements of different stages in a process

Each stage in this process has its own page, with a table of key elements. A PPR report creates an overview of the essentials all on one page, with links to the details. Title is sorted in ascending order so the stages are listed in the correct order.

Showing key elements of sequential milestones

Here, each milestone has a detailed page with metrics, exit criteria, and so on, and the PPR only summarizes some key information. The page titles include a number for sorting, since the milestones aren’t in alphabetical order. I used the Deck of Cards macro to create tabs for each milestone that could be browsed sequentially, with the PPR overview appearing on the first tab.

FAQs

As I wrote about in FAQs - several methods to create them, the PP / PPR macro combo can find and list brief FAQs anywhere in a wiki space. Different Page Properties ID’s and labels can be used to group or categorize FAQs.

Catalog or directory of pretty much anything

This is an ideal use for the PP and PPR macros. Here are a few examples.

Product listing

I’m testing this proof of concept that includes a thumbnail image of the listed items. Some products have their own page; some products are grouped on a single “product group” page. The PPR can list them either way.

Tool directory

Lists tools used by our firmware engineers along with the URLs, subject matter experts and tool owners.

Team directory

One lab includes several teams which each have their own section in the wiki space. The team directory lists all the teams, their members, and links to other resources.

Specifications or links to more detail from a sequence diagram

This is another proof of concept page where the links in the sequence diagrams, added with special syntax, are the tinyurls to wiki pages. Click on a step in the diagram to go to the wiki page for more detail. The sequence diagrams are autonumbered, and the PPR macro below the diagram includes a column for the sequence number, so the steps can be sorted sequentially. This is still being tested as adding or removing steps in the sequence diagram means the pages change too, but you get the basic idea.

Link list from other pages

One of our engineers created a list containing the links he used most often on each of the child pages. Now he can click through without having to visit the child page first.

TOC list from other pages

I couldn’t get a TOC macro from a different page to display within the PPR, so I copied and pasted the text of the TOC (which uses absolute URLs) into the PP macro instead. This isn’t a perfect solution, but at least I only have to change the child page and not the parent.

Test results

This was a really clever (and complicated) use of the macro combination and I’ll write a separate post about the implementation. An engineer and a tester used the macros with specific filtering, child pages, and labels to list all the runs for a specific test, and all the results.

• Test Case pages contain a PPR report generated by the Test Run pages that shows all the Test Runs the individual tests have been executed in.

• Test Run pages contain three PP macros (setup, overall run results and individual test results). The header column of the PP macro for the individual test results contains a link to the Test Case page. This is used for filtering on the Test Case page.
  
  

• Test Run History pages contain a PPR macro that lists the overall run results for each Test Run.
  

Display tweak

I had minimal real estate for displaying the most recent Forum meeting out of several PP macros on the same page. I was able to use a CSS stylesheet to suppress the display of the header row, the pagination at the bottom of the listing, and the first column which by default contains the page title. The second column contains the Forum topic. (Your code may vary depending on your version of Confluence.) The CSS will affect all PPR macros on the page.

/* Suppresses the display of the header row */ 
.tablesorter-headerRow {
 display: none; 
} 
/* Suppresses the pagination at the bottom of the listing */ 
.macro-auto-pagination {
 display: none; 
} 
/* Suppresses the default column that contains the page title */ .title { display: none; 
}

End user considerations

The most common errors end users make are easy to fix.

• Changing the text in the header column in the PP macro table

• Omitting labels on the pages to include.

I sometimes call the “properties” created by the table “metadata” as an aide to understanding, as our engineers apply metadata to some parts of their work on a daily basis.

ServiceRocket’s Scaffolding and/or Live Template add-ons could be leveraged for consistent data entry and/or maintaining the consistency of the PP table across many pages. For most end users though, the PP / PPR macro combo is the most accessible. It’s surprisingly versatile and I look forward to exploring other creative uses for it.

[Jasmine Andrews]

Some great use cases here! Going to bookmark this one for when I have time to sit with a cup of tea and give it a proper read. 

I've only given it a quick scan read but noticed the jokes example. This could probably support FAQ style usage, right? Exciting!