Ever felt lost in the Page editor due to dynamic content? Pages that render dynamic content, like transclusions or lists of document references, often look totally different in the browser. This feature does render the text content of selected dynamic macros.
This is an experimental feature at a very early stage of development. It allows to render the macro shown in the page editor and add this dynamic content right below its macro.
This dynamic content helps authors to navigate to the right position within the editor.
Details
Some details on how to use this tool.
Experimental Status
This feature has been release with version 5.0 of the projectdoc Toolbox as experimental.
The basic functionality is there, but some work is still required. For instance accessibility is missing. You need to use the mouse to get the macros and rendered content to collapse and expand. The controls are not yet very intuitive, meaning: if you do not know the feature, you will probably not learn it without reading this documentation.
Further limitations (selection):
- The rendered content is deleteable - does not hurt, but may be confusion especially for novice users
- It may be cumbersome to work with the rendered content in the editor - we are evaluation the use cases currently
- Does not update on changes to the macros - it is just meant as an orientation for the author once the editor opens
- Rendering is done in editor mode - so the content is not exactly rendered as in view mode (missing styles, missing icons)
- Copying and pasting content may result in dynamic content to be saved as genuine content - can be easily removed, but is probably very confusion for novice users
- Does not work in editor of a new page
Currently there is no target date or version when this feature will be considered production-ready. Experimental features may be removed, if it turns out that there is no demand for it or if it is technically not feasible to provide it in a manner users expect it to work.
Feedback is welcome!
What does it do?
The rendered content is rendered inside the page in the page editor.
The following screenshot shows the macros with their rendered content below. The first macro is the Transclude Documents Macro, the second macro is the Display Table Macro.
With a single click you may remove the macros from the view.
Or you may remove the rendered contents from the view.
How does it work?
You may interact with the macro or the rendered content.
For the macro and the rendered content you need to click on the chrome, for instance on the macro head or the upper margin of the rendered content.
Macro
When clicking on the macro you change the state of the associated rendered content.
| Action on Macro | Result |
|---|
| Shift-Click | Toggle the state (show / hide) of the associated rendered content. |
| Ctrl-Click | Toggle the state (show / hide) of all rendered content dependent on the state of the associated macro's rendered content you actually clicked. You click on the macro, but the state of the associated rendered content decides what state all rendered content will be put. If the associated rendered content is shown, all rendered content will be hidden. If the associated rendered content is hidden, all rendered content will be shown. |
Rendered Content
When clicking on the rendered content you change the state of the associated macro.
| Action on Rendered Content | Result |
|---|
| Shift-Click | Toggle the state (show / hide) of the macro associated with the rendered content. |
| Ctrl-Click | Toggle the state (show / hide) of all macros dependent on the state of the rendered content you actually clicked. You click on the rendered content, but the state of the associated macro decides what state all macros will be put. If the macro of the associated rendered content is shown, all macros will be hidden. If the macro of the associated rendered content is hidden, all macros will be shown. |
How is it integrated?
Users in the group of confluence-administrators are able to activate and deactivate (default) the feature on the Features control panel.
In case you find this feature confusing or it interferes with other tools you use on your Confluence platform, simply deactivate it.
The feature may also only be activated for the listed Confluence groups. If no group is specified there is no restriction.
Administrators may also specify the names of macros that use the feature to render dynamic content.
You may use a wildcard at the end of the macro name which will match all macro names with the given prefix.
Note that you are not restricted to macros provided by the projectdoc Toolbox.
Further you may control whether the macro and / or the rendered dynamic content is shown when a user opens the page editor. In case you deselect both checkboxes, the system will render the macro.
Resources
More information on the topic of tools for editing is available by the following resources.
