Doctypes and the Name List Macro allow to specify a range of valid tokens for a value. These values can be rendered by applying specific CSS styles.
Define the Range of Values
Defining a value range is a one-time configuration effort usually designed and conducted by the documentation architect and/or the documentation gardener.
For this example we want to define this range of values:
| Value | Description | Order | Style |
|---|---|---|---|
 | No team member is currently working on the task. Therefore it is currently open. | 00100 | background-color: red; |
 | The team is working on this task. | 00200 | background-color: orange; |
 | The team has finished the task. | 00300 | background-color: green; |
Create Document Instances
For each value you need to create a document where you add the information or metadata for this value.
Select Doctype
First you choose the doctype. For status codes the use of the Tag doctype seems natural.
Create Parent Tag
To group all our status codes we define a parent tag document first.
You may add any information to this document, but its main purpose is to hold our three status tokens together.
Create Value Range
Add as child to the parent tag a new document for each value of your value range. All of these values are based on the Tag doctype.
Now we need to add some document properties to define the order of the values (Sort Key) and their visual representation (CSS Style Information).
Please make sure that the value for the CSS Style Information is indeed proper CSS (including the semicolon at the end!)
Note that the third column of the table contains document property controls where we add the hide control. This will signal the renderer that this line is of no interest to our readers and is therefore not visible in the view mode of the document.
Add one document for each value of your range as a child to the Status tag document.
This is the result:
Autolist tagged Documents
The doctype instances typically automatically list all documents with a given value using the Display Table Macro. This is very handy for a small amount of documents tagged with a given value (for larger sets of documents you may want to list them using different queries on dedicated pages).
Go the the Section with title Documents and change the Where parameter according to your selection requirements.
The example selects on the property name 'Status' (per default the doctype selects on the 'Tags' property).
$<Status> = [${Name}]
You'll find this name used in the following steps of this example.
For more information on how to specify search criteria, please refer to Search Tips!
Fixed, plain Values
If you do not need to add values dynamically as shown in this example, you can choose from a set of Selection Macros. An example for such a macro is the Iteration Macro with a predefined set of document iteration steps.
You cannot change the values of the macro. You cannot document your semantics of the values. It's take it or leave it.
Use the Value Range
Using the value range comprised
- the definition of a property using the value range by the template author (template) or author (document instance)
- the selection of an actual value by the page author
Define Range Property
To use the value range in your documents you typically ask the template author to define a blueprint and add the configuration to the template. In this example we will do this manually first. That is the a property is manually added to a document instance by the author.
Per Instance
For this example we assume that the author creates a Topic document.
Add a new property called 'Status' to the document by adding a line to the properties table (within the Document Properties Marker Macro). Use the Name List Macro as a value to the property.
Open the macro editor for the Name List Macro and set the following parameters:
| Parameter | Value | Explanation |
|---|---|---|
Doctype | tag | Select on the Tag doctype. Please note that you specify the identifier of the doctype and therefore it is all lower-case. |
Property | Status | This is not mandatory and only affects searching if specified via a blueprint. |
Where | $<Parent>=[Status] | Select the valid values for this property. By defining an exact match we restrict the range to those values of doctype Tag whose parent document is the Status document we created in step one. |
You may also limit the search for valid values on specific spaces. Please refer to Delegate Space for more information on how to use delegate spaces to define common information that applied to all delegating spaces.
Why not Tag List Macro?
Since we use the Tag doctype you may ask why we use the Name List Macro and not the Tag List Macro. The difference between the two is that the latter also includes the labels of a page as values. Since you want to control the range of valid values, the Name List Macro is a valid choice.
If you save the page, you'll see ... nothing!?!
That is because we just have defined a property and a valid range of values, but actually did not select one. Properties without a value are not shown by default (to not clutter the view with non-information).
The template author may select one as default, which would be 'Open' in this example or leave the selection completely to the author. See Select a Value for details.
Select a Value
To select a value the author can check the valid set of values by deselecting the Empty Where Clause Handling.
Select one of the values and set it as the value to the Names parameter.
Save the macro and then save the page. The result is this:
