Changing the rendered contents of a projectdoc document dynamically for each request.
If you need to render a Confluence page dependent on the context of the caller, one form of implementation is to respond to the reader's request. This feature of the projectdoc Toolbox for Confluence is called Remote Controlled Document.
The configuration of many macros of the projectdoc Toolbox can be controlled by providing a HTTP query string to the page URL pointing to a page.
Control Query
For instance the Display Table Macro is used to list projectdoc document references according to specified query criterias. Therefore it works similar to the Page Properties Report Macro provided by Confluence. In contrast it provides Where or Select parameters instead of CQL.
Additionally the Display Table Macro can be remote controlled by adding a HTTP query string to override macro parameters on the targeted page. This effectively changes the query criterias and in consequence the rendered list of documents on that page.
Control Transclusion
Another example is the transclusion of page fragments which can be controlled by altering parameters of the Transclude Documents Macro or the Transclusion Macro.
As in the previous example these macros expose their parameters to be overridden by parameters of the HTTP query string by the caller. Therefore the caller can again control the contents of the page – i.e. what is transcluded by the macros.
One use case is allowing to render information from a remote information system on a page. A system may render the documentation for error codes by adding context information about the error to the request URL that points to a page on the Confluence server.
Another use case is to render a page from the context of the calling page. With version 2.4, the Wiki Link Macro allows to provide request parameters. This way a reader clicking on a link created by this macro has a view on the rendered page that knows the context of the page the reader is coming from. This tip will show this use case in detail.
Suppose you have a Library Space that collects all external resources for a selection of work groups. The teams of the work groups may have their individual Workspaces with a Space Index rendering all resources from the library using a Display Table Macro. Alternatively the workspaces could use the Wiki Link Macro to render a link to the resources homepage of the Library Space and control the selection criteria by overriding the Where parameter of the Display Table Macro on that page.
ID for Display Table Macro
To control a macro remotely the macro needs to have an identifier.
For instance add the identifier pd-documents to the Display Table Macro.
Wiki Link Macro
The Wiki Link Macro provides a Request Parameters parameter to configure.
First specify the page to link to. Since we are addressing the homepage for resources on a delegate space, we use the Page parameter to specify the name.
We assume that the library space is already configured as a delegate space and the work space has no Resources page.
Next we set the request parameters:
pd-documents:where=$<Tags>=[My Workgroup]
Result
The label is in italic indicating that the (in our case) the resources are on a delegate space.
The URL generated with the Wiki Link Macro looks like this:
.../confluence/display/MYSPACE/Resources?pd-documents:where=%24<Tags>%3D[My+Workgroup]
The resources page of the library for the request launched by clicking the Resources link will only contain resources that are tagged with "My Workgroup".
It depends on your use case whether to have a individual resources pages on each space or reuse a central resource page on a delegate space that is remote controllable.
This tip simply wants to remind you that the projectdoc Toolbox supports Remote Controlled Documents.