Alter the rendering of macros of transcluded content with remote controls.
Task
Suppose you have pages with references you want to collect and render in a display table.
For this example we use the documentation 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:
Requirements
To grab information from these three documents, two requirements must be met:
- The table of references is required to be selectable
- The display table macros require an identifier of tag
Selectable Table of References
In our task we want to select the name and short description as properties and the table of references. The table of references is part of a Section Macro and therefore selectable. But we do want to have the table alone without the intriduction text.
Therefore the table is wrapped inside a Content Marker Macro with identifier documents.
Since the Display Table Macro renders each property and section in a column identified by the name or title – in our case identifier – we need to make sure that the identifier provided to the Identifier Parameter of teh Content Marker Macro has the same value in all three documents.
Selectable Display Table Macro
In order to remote control the Display Table Macro the macro requires to be identifiable. This can be done by either providing a value to the Identifier Parameter or the Identifier Classes Parameter.
We decide to provide the identifier references.
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.
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 colums, use a Template as a value for the Select Parameter.
#T\{$[Name]<br/>${Short Description}\}, documents
Note the \. 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):
