Links allow readers to find related information. Autocomplete allows authors to recall the names of related information. Let's have a closer look on the Autocomplete Feature of the projectdoc Toolbox!
Autocomplete Parameter Values
The Autocomplete Feature currently supports authors to edit values of macro parameters. Macros are used for rendering, referencing, compiling, and transclusion, or multiple purposes. Macros of the projectdoc Toolbox that deal with referencing do this by identifying a document either by space and page title or by doctype and name. To select the title or name, the Autocomplete Feature provides support.
The Autocomplete Feature also allows to select doctypes for macro parameters and – currently for only one macro – the property names.
Name List in Action
The Name List Macros require a doctype to be set. Without a doctype these macros will not offer any names for selection.
Once a doctype is selected, no character is required to be entered to present a list of valid values. If the parameter field has the focus, simply press the down key or hit space to show the valid values in a selection box.
In addition to the Doctype parameter, the result set can be further constraint by the parameters Space Key, Space Keys, and Where.
The sort order can be controlled by the Autocomplete Sort parameter. If not specified, the natural sort order is applied.
Template authors can also control the multiplicity – one or multiple values – and the tagging – are unknown names allowed or not (note that the macro editor is required to be restarted to apply changes to the following properties).
For more information on how to use these parameters, please refer to Autocomplete.
Display Document Property in Action
The Display Document Property Macros allow to select multiple documents. At least two characters are required to be entered to start the Autocomplete.
The feature "Pasting URLs" to a macro parameter value did not make it into the first release of Autocomplete.
The placeholder text "... paste URL" is therefore currently misleading. This will probably be available in one of the next releases.
Further constraints can be specified by the Autocomplete Constraints parameter. The sort order is specified by Autocomplete Sort. Again, if not specified, the natural sort order is applied.
Space Property Constraints
Currently there is only one space property to put constraints on the result set for names to be presented for Autocomplete: Autocomplete Active Constraint.
This property specifies a constraint that must be met be names in the result set in addition to constraints defined by macro parameters. The property can be used to define that only names from documents that are in Iteration Released, Production, and Deprecated should be presented for selection. Please refer to Autocomplete Active Constraint for an example.
Explaining the Where Clause
The Where clause shown above shows every doctype besides Event and Todo only as an option in an autocomplete if it is in Iteration Released, Production, or Deprecated. In case of an Event or Todo, the Iteration needs to be in Facade, Filled, Focused, Finished, or Released.
With this constraint only tags that are ready for use are rendered as options. On the other hand, events and todos are only options in case they are not completely done.
( ($<Iteration>~(Released,Production,Deprecated) NOT $<Doctype>~(event,todo)) OR ($<Doctype>~(event,todo) AND $<Iteration>~(Facade,Filled,Focused,Finished,Released)) )
The contraint must be a valid Where clause fragment. For more information on queries with the projectdoc Toolbox, please refer to Search Tips.
Caveats
Some tips on using Autocomplete that may save some time on occasion.
Doctypes missing
In case the Doctype parameter does not show all expected values, the doctype cache may be corrupt. In this case a user with appropriate access privileges needs to refresh the doctype cache.
For more information on refreshing caches, please refer to Cache Refresh Actions.
Macro Parameter Panel
The support for setting macro parameters can be extended to the macro parameter panel. Confluence provides such a feature for the Status Macro, the projectdoc Toolbox for the Iteration Macro.
Macro parameters for the Names parameter will be shown in a selection box. Currently the focus handling has some issues. Therefore this feature is turned off by default. Administrators may turn it on in case it supports the productivity of their users more than the quirky focus handling offends them.
See Autocomplete for details on how to do this.
References
- Erfolgsmuster: Strukturierte Faulheit
- Article in a German magazine by Peter Hruschka und Gernot Starke "Erinnern kann Papier erheblich besser als Hirn" (translated as "Paper recalls much better than the brain").
Both authors share their insights in documenting software systems and software architectures by publishing their arc42 Template. There are plenty of resources on the internet. In case you are using the projectdoc Toolbox you may have a look at the arc42 Doctype Add-on which provides the arc42 Template for Confluence. - I admit I have heard the rumor that some people actually do not like to write or read documentation.
