Task

Suppose you have pages with references you want to collect and render in a table.

For this example we use the Online Manual for the projectdoc Toolbox and want to render the name, short description, and referenced documents with the Display Table Macro.

These are the documents we want to transclude from:

1. Tours
2. Topics
3. FAQs

Requirements

To grab information from these three documents, two requirements must be met:

1. The table of references is required to be selectable
2. The display table macros require an identifier of tag

Let's see how we meet this requirements!

Transclusion and Remote Controls

Using a Display Table Macro to render the name, short description and documents property has per default the following result:

We use Name, Short Description, documents for the Select Parameter and translate documents to References (documents=References) by the use of the Header Translations Parameter.

The problem is that the documents are rendered differently in the three locations. In this view we need to have a unified format. The unified format should only render the name and short description. We also want – since the value is rendered in a table cell – the list of references be rendered as a definition list and not as tables.

We use the Remote Control feature and are able to control all three transcluded macros by the use of the identifier references (as we have shown in the Requirements section above).

We set the Remote Controls Parameter to 

references:select=Name, Short Description&references:render-mode=definition

What does this mean?

references is the identifier of the macros we want to remote control. We set the Select parameter to Name, Short  Description. Not only do we want to have each cell render the same properties, but also a definition list is only rendered in case there are only two properties selected.

The second control is adjusting the Render Mode to definition, which will render the table as a definition list.

So this is the result:

In case you want to collapse the Name and Short Description columns, use a Template as a value for the Select Parameter.

#T\{$[Name]<br/>${Short Description}\}, documents

Note the backslashes (\). They are necessary because of an issue with the macro editor. It has difficulties parsing values with curly braces. The backslash escapes it properly, so the macro editor will close successfully.

We also need to translate the name of the template T to Name. So the Header Translations read like this:

documents=References, T=Name

So this is the result (only the first row shown):

Conclusion

We have shown how the result of a Display Table Macro can be rendered more concise.

By the use of Remote Controls we turned tables in different format into a definition list. By the use of a Select Template we collapsed the first two columns into one.

The focus of this tip is on using Remote Controls. It requires some configuration on the part of the transcluded content. The use of transclusion should be already considered when designing the information architecture. But – if the user has write access to all transcluded content – we have shown that adjusting the content is not too difficult.

Resources