- Created by Robert Reiner, last modified on 01. Jun 2021
projectdoc Toolbox
Renderes an index over the section on a document with intra-page links.
- Tags
- Identifier
projectdoc-section-index-macro- Since
- 4.8
The Section Index Macro creates an index with intra-document links to all sections local in the macro body. This is a navigation tool to quickly jump to sections with a document as it provides an overview over the element in tabular form.
Sections may be defined locally by the use of the Section Macro or be transcluded. Local and remote sections can be compiled by the Section Compiler by Reference Macro. Local sections may provide a short description and additional properties inside a Content Marker Macro.
Parameters
The macro is configured by the following parameters.
Select
Specify a comma-separated list of document properties or section names to display.
If not specified, the name and short description of the document is displayed per default.
Count Columns
The last character may also be a '#' in which case the property value is applied to the Count Function. The Count Function counts the number of table rows, number of list items, or number of definition terms (whichever of these three is encountered first). Otherwise the count function returns zero. This allows to render the count of a result set rendered in a section.
The Count Macro also provides this function to the contents of its body.
Header Translations
Comma-separated list of key value pairs. Key is the header to be replaced by the value. Format: k1=v1, k2=v2.
Use this parameter if the name of the property is not appropriate as the column header.
The default label '#' may be overridden locally like this:
#=Counter
The label of all number column headings is also controlled by a space property named Counter Column Header.
Calculation Columns
List column names to apply for calculation. The column names are separated by comas.
Per default the values are treated as integers. You may select the number type by the following selectors:
| Selector | Description |
|---|---|
| i | Integer value (Long Precision) |
| f | Float value (Double Precision) |
Separate the selector with a colon from the column name (e.g. Value:f).
If you require to specify the number format, add it after an equal sign (e.g. Value:f=#0.00).
Use the following symbols to define the pattern:
| Symbol | Description |
|---|---|
| . | Decimal Separator |
| 0 | Digit |
| # | Optional Digit |
| , | Grouping Separator |
¤ | Currency Sign |
| % | Multiply by 100 and show as percentage |
‰ | Multiply by 1000 and show as per mille value |
| ' | Quote strings (to escape symbols) |
The sum is rendered in additional row. The td element is rendered with the CSS selector projectdoc-calculated-value.
Render Mode
Controls how the table should render properties of the document result set.
There are three render modes: table, list, and section.
Table Render Mode
If you want to render the result in a table, leave this parameter value blank.
You may also explicitly set this value to table.
Add a CSS class by separating it with a "=".
Setting the widths of the columns is supported. Added a columns descriptor in brackets after the CSS class name. The comma-separated list of width is passed as CSS style values for the width attribute.
=mystyletable=mystyletable=mystyle[columns=20px,120px,80px]
Since 5
Since version 5 of the projectdoc Toolbox besides commas also semicolons are allowed to separate the column width.
table=projectdoc-alternating[columns=220px;*;220px]
Since version 4.11 the columns must provide a value for the counter column (if selected).
These CSS classes are provided by the projectdoc Toolbox to style your tables:
| Name | Short Description |
|---|---|
| projectdoc-alternating | Use the CSS class projectdoc-alternating for a HTML table to get alternating colored table rows. |
| projectdoc-counter-column | Marks column cells that contain a row counter. |
| projectdoc-fullwidth | Use the CSS class projectdoc-fullwidth for a HTML table to get a table using 100% of the available width. |
| projectdoc-halfwidth | Use the CSS class projectdoc-halfwidth for a HTML table to get a table using 50% of the available width. |
| projectdoc-quarterwidth | Use the CSS classprojectdoc-quarterwidth for a HTML table to get a table using 25% of the available width. |
| projectdoc-selected-document-properties | Rendered with a properties table in front of transcluded content. |
| projectdoc-thirdwidth | Use the CSS class projectdoc-thirdwidth for a HTML table to get a table using 33% of the available width. |
List Render Mode
You may render a two column result in a list. Usually this is the case for the document name and short description.
The following values are valid:
definition- for a definition listnumbered- for a numbered listunnumbered- for an unnumbered listplain- for a comma separated list as text
Plain text in plain list
If the list render mode is set to plain, then the elements of the list are still rendered as specified with the Select Parameter.
In case you need to render a plain list (aka comma-separated list) then you could set the Select Parameter to Name-.
You may add a CSS class by separating it with a "=".
If you add a "-" at the end, the first character of the second column value (e.g. the short description) will be lower cased.
Note that there is specialized macro for rendering lists with an easier interface: Display List Macro.
The render mode parameter allows to switch between tables and lists quickly, if you started with a table, but later decide to use a more compact format for your two-column result.
Here are a few examples with valid values:
| Value | Description |
|---|---|
definition | Renders as a definition list. |
unnumbered- | Renders as an unnumbered list. The first character of the second column value is lower-cased. |
definition=simpleindent- | Renders a definition list with class simpleindent. The first character of the second column value is lower-cased. |
Section Render Mode
To render the result with vertical tables in sections, the parameter value has to be an asterisk ('*') or an integer between 0 to 6, optionally be followed by a "+".
Since 4.5
The asterisk ('*') allows to calculate the heading level dynamically, similar to the feature provided by the Section Macro.
Otherwise there is a separate table for each document, where the first column contains the name of the property, the second its value. If the digit is zero, there will be no heading generated in front of the table. The first property in the select clause provides the value for this heading.
If a "+" sign is added (e.g. "2+"), the first property will be rendered in the heading and in the first row of the table. You may use this option to render the name as the heading and as a link in the first row of the table.
Since version 1.17 the properties table may be rendered as definition list (append an 'l'). Also the widths of the table may be controlled. For both representations a CSS class may be applied.
*1l- 1+l
1=mystyle[columns=120px,250px]
Styles for definition lists provided by the projectdoc Toolbox are documented in Definition List Macro.
Since version 4.5 the short description can be extracted to be rendered in front of the table by placing the character 's' after the level (e.g. "*s").
Since version 4.5 the additional modifiers for the section render mode may appear in any order after the level is specified.
Caption
The label for the table caption.
No Table Heading
If checked no heading will be rendered.
Since version 1.17 this parameter also applies for the table above the sections in Section Render Mode.
Identifier
Unique identifier for the rendered content.
This identifier is used for Remote Control and Context Controlled Macros.
Identifier Classes
Apply identifier classes to render this macro as part of a group.
This identifier is used for Remote Control and Context Controlled Macros. Multiple macros on a page may have only one unique Identifier, but may share common identifier classes.
Context controlled
When checked configures parameters via document and space properties.
For more information please refer to Context Controlled Macros.
Remote Controls
List of controls to pass to transcluded contexts. Controls are separated by ampersand ('&').
Since 4.5
Available since version 4.5 of the projectdoc Toolbox.
This allows to control the rendering of remote controllable macros by sending controls. For more information please refer to Remote Control.
To alter the rendering of a remote control macro identified by id 'docs', use the following controls:
docs:select=Name,Type&docs:render-mode=definition
The tip Remote Controls for Transclusion provides a short introduction in how to use this feature.
Since 4.13
Since version 4.13 the parameter supports to reference a space property. The name of the space property has to be prefixed with the paragraph sign ('§').
For instance, if the value for the select parameter is specified by the space property my-select, then the value of the select parameter is §my-select.
Macro Body
Use the Section Macro to add local sections to the body of the macro. To provide a short description or additional properties for this sections, use the Content Marker Macro.
Provide Short Description
If the section should mimic a short description that is rendered in front of the document properties table, then use the Content Marker Macro with parameter CSS Classes set to projectdoc-short-description.
Provide Document Properties
To provide additional document properties for a section, add a Content Marker Macro with parameter CSS Classes set to projectdoc-selected-document-properties.
If the document properties should not be shown in the section, use projectdoc-hide
Resources
- Section Macro
- Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
- Section Compiler by Reference Macro
- Compiles local sections with transcluded content by a reference list.
- Content Marker Macro
- Marks a piece of content within a document. This content can be referenced for transclusion.
- projectdoc-selected-document-properties
- Rendered with a properties table in front of transcluded content.
- projectdoc-hide
- CSS class to remove the tagged element from the view.
- projectdoc-short-description
- Marks a block element to contain a short description of a document.
