- Created by Robert Reiner, last modified on 03. Feb 2022
projectdoc Toolbox
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.
- Audience
- Categories
- Tags
- Selectors
- ownMacroStyle
- ID
projectdoc-section
- Type
The Section Macro renders a section with a title and its content. The content is added to the macro's body.
If the content is empty, the section will not be rendered. This macro is an essential element for template authors. The structure of a template for a document type can be defined so that document authors have guidance which information to place where. But as long as no content is provided by the document author, the reader of the document is not distracted by empty sections.
![](/confluence/download/thumbnails/6554554/topic-view-snip.png?version=1&modificationDate=1493238988000&api=v2)
Properties
Title
The section title to be rendered. The section title will also be used as an unique identifier of the section within the document.
The title will be normalized to an HTML id attribute value that can be used as an anchor in a reference.
The standard mechanism provided by Confluence is used to calculate this identifier. Basically the identifier is stripped from any spaces. If the identifier is not plain letters, a prefix of "id-" is added to the identifier. This is especially the case, if an identifier does not start with a letter. The generated identifier is conform to HTML 5.
Usually document authors do not have to bother with the structure of the id attribute.
From version 1.7 on the title is mandatory. This allows authors to create the macro and add a title with greater speed.
Level
The level of the heading. This will create an HTML header element.
If you are using version 1.7 of the projectdoc add-on and you are running Confluence in version 5.8, the level '*' is supported to calculate the level automatically.
A section with level '*' located top-level will be considered to be at level 1. If a section with level '*' is inside a section of level X, it will be moved to level X+1. Therefore users may now safely choose the default level of '*' and let projectdoc calculate the level of the sections automatically. This is especially useful if you decide to move a section within another using drag-and-drop.
If the macro is executed inside an older version of Confluence (less than 5.8), the star is always resolved to level 1. That is you have to control the level manually.
Delegate on Empty
If checked (default), the macro transcludes the section with the same name as this section from the delegate document, if the content of the section is not empty.
You may control the output if the referenced section is not available in the delegate document. Per default, nothing is rendered (same as in the case the section in the delegate document is empty). If you set Delegate Document Suppress Error Message Section to false
, an error message will be rendered in the delegating page.
If no delegate document is provided with the Document Properties Marker Macro, this parameter has no effect.
For Information on using the delegation feature for properties, please refer to delegate.
Available since version 1.10.
Localize Links
Check if links in transcluded content should be re-targeted to the current page.
This is especially useful if content is to be exported to PDF or Microsoft Word.
Show Title
If this box is unchecked, the title will not be rendered.
Since version 1.7 on the title is mandatory, this checkbox - also available since version 1.7 - is necessary if the section should be displayed without a title.
Identifier
The identifier uniquely identifies the content within the document. This overrides the title as the default.
An HTML element will be rendered with this identifier as value to the HTML attribute id
.
If the identifier has the hashmark as prefix, it is used verbatim. If the prefix is not a hashmark, the system will ensure the uniqueness of the element within the space and on the page.
Since 4.9
The verbatim identifiers are supported since version 4.9 of the projectdoc Toolbox.
Tags
Allows to tag the content for transclusion with the Transclusion Macro. You may specify more than one tag in this comma separated list.
Intro Text
Allows the template author to add a text to introduce the content. Any text added here is considered as not present, if the content is empty. If you are not designing a document template, this attribute is of little use and you will probably add the text to the macro's body.
Extro Text
Like the Intro Text property, but will be rendered after the section's content.
Hide
The flag allows to not render the content, if checked. Use this parameter to temporarily hide content from being show to readers.
Consider Empty
If this parameter is checked, then the content is considered to be empty for all checks conducted by the projectdoc Toolbox.
This allows users to add content that is only rendered in case content that is not empty or considered empty is actually present.
This is similar to the Intro Text and Extro Text parameters whose content is also only rendered if the content of the section is not empty.
Since 4.5
This parameter is available since version 4.5 of the projectdoc Toolbox.
Ignore Template Buttons
If checked template button macros are regarded as whitespace.
This allows to add a template button to create subordinate pages without rendering the section just because of the button being part of the body.
Ignore Elements
If checked HTML elements that do not provide text information are considered empty.
For instance a table with no table date text content, providing only header text, are considered empty if the box is checked.
Since 5.0
This option is available since version 5.0.4.
Required Roles
Readers require the given roles to have access to the content. If not specified, the content is accessible to anyone.
The Content is not secure!
Please note that this is only a convenience for the user. The content of the box is for example still indexed by Lucene or will be displayed, e.g. if the user has access to the page's source code or there is a preview function on a page.
Therefore do not add confidential information!
The hiding mechanism is therefore to be considered on the same level as hiding HTML fragments by means of CSS or client-side JavaScript. The user has access to the information.
Especially do not use this macro for property values with the Document Properties Marker Macro! Use this macro in document bodies only.
Note on using confidential information: If allowed by your information policy, put confidential information on a separate page (using page restrictions to control access) and use the Transclusion Macro to render it on a page.
The user must have one of the specified roles, not all, to access the content.
Add the name of roles here you have (optionally) defined with a role document. It is required that the name of the role is created as a Confluence group.
Case insensitive
Note that while Confluence group names are required to be lower case, the names of roles may still be provided in mixed case.
Required Permissions
Readers require the given permissions to have access to the content.
The Content is not secure!
Please note that this is only a convenience for the user. The content of the box is for example still indexed by Lucene or will be displayed, e.g. if the user has access to the page's source code or there is a preview function on a page.
Therefore do not add confidential information!
The hiding mechanism is therefore to be considered on the same level as hiding HTML fragments by means of CSS or client-side JavaScript. The user has access to the information.
Especially do not use this macro for property values with the Document Properties Marker Macro! Use this macro in document bodies only.
Note on using confidential information: If allowed by your information policy, put confidential information on a separate page (using page restrictions to control access) and use the Transclusion Macro to render it on a page.
Permission | Description |
---|---|
no-permissions-required | The content is accessible by anyone who has access to the page. |
not-authenticated | Users are required to be not authenticated to have access to the content. This allows text to be rendered in case a user is authenticated or not authenticated. Since 4.2.1 This option is available since version 4.2.1. |
authenticated | Users have to be logged in to access the content. Usually you have to be a team member in the role of a reader to access the content. |
write-access | Users have to have write access to access the content. The content will only be rendered to authors. |
The space property Pretend Being A allows to override this value.
Required Document Properties
The listed document properties are required to be set to a non-empty value to show the content.
The names have to be comma-separated.
The Content is not secure!
Please note that this is only a convenience for the user. The content of the box is for example still indexed by Lucene or will be displayed, e.g. if the user has access to the page's source code or there is a preview function on a page.
Therefore do not add confidential information!
The hiding mechanism is therefore to be considered on the same level as hiding HTML fragments by means of CSS or client-side JavaScript. The user has access to the information.
Especially do not use this macro for property values with the Document Properties Marker Macro! Use this macro in document bodies only.
Note on using confidential information: If allowed by your information policy, put confidential information on a separate page (using page restrictions to control access) and use the Transclusion Macro to render it on a page.
The property names are allowed to be prefixed with an exclamation mark (!
) in which case the content is only shown if the value of the space property is not blank.
It is possible to check for a certain property value.
property-name=my-value,!property-name2=other-value
In case the properties list is starting with a pipe character ("|") then at least one of the properties is required to match.
Since 4.2
The OR semantics are supported since version 4.2 of the projectdoc Toolbox.
Required Space Properties
The listed space properties are required to be set to a non-empty value to show the content.
The names have to be comma-separated.
The Content is not secure!
Please note that this is only a convenience for the user. The content of the box is for example still indexed by Lucene or will be displayed, e.g. if the user has access to the page's source code or there is a preview function on a page.
Therefore do not add confidential information!
The hiding mechanism is therefore to be considered on the same level as hiding HTML fragments by means of CSS or client-side JavaScript. The user has access to the information.
Especially do not use this macro for property values with the Document Properties Marker Macro! Use this macro in document bodies only.
Note on using confidential information: If allowed by your information policy, put confidential information on a separate page (using page restrictions to control access) and use the Transclusion Macro to render it on a page.
Property names are allowed to be prefixed with an exclamation mark (!
) in which case the content is only shown if the value of the space property is not blank.
space-property-name=my-value,!space-property-name2=other-value
In case the properties list is starting with a pipe character ("|") then at least one of the properties is required to match.
Since 4.2
The OR semantics are supported since version 4.2 of the projectdoc Toolbox.
Apply Document Properties
If checked (true
) properties of the document and space are applied to resolve placeholders.
The standard placeholders are supported:
${...}
- text replacement$<...>
- HTML replacement$[...]
- text replacement with link to current document
Since 5.0
This parameter is supported since version 5.0 of the projectdoc Toolbox.
If space default is selected, the behavior is controlled by the space property Apply Properties to Content (projectdoc.macro.content-marker.apply-document-properties
).
CSS Classes
Specify the CSS classes to be attached to the created section.
Assume an index contains h2
, ul
, and link elements.
The following CSS statements format the main index for a container with a class attribute value of projectdoc-topic-main-index
.
/* Headings */ .projectdoc-topic-main-index h2 { color: #FFA62F; margin-top: 10px; font-size: 12pt; } div.hasIdOrTags.projectdoc-topic-main-index { opacity: 1.0; } /* Lists */ .projectdoc-topic-main-index ul { color: #3B73AF; margin-top: 0px; margin-bottom: 9px; } /* Links */ .projectdoc-topic-main-index a:link, .projectdoc-topic-main-index a:visited { color: #3B73AF; } .projectdoc-topic-main-index a:hover { color: #F87217; } .projectdoc-topic-main-index a:active { color: #C35817; }
Add these statements to the space stylesheet:
The result for the example above:
Since version 2.0 of the projectdoc Toolbox it is possible to style the section even more easily. Instead of defining your own CSS classes, you can take advantage from a set of predefined CSS classes to support rounded boxes and different colors.
Using the CSS class projectdoc-section-box applies the following styles to a block element:
.projectdoc-section-box { border-radius: 25px; padding: 20px; margin-bottom: 5px; margin-top: 25px; }
Now in conjunction with three templates for CSS classes colored boxes can be rendered:
- heading font color:
projectdoc-h-COLORNAME
- content font color:
projectdoc-c-COLORNAME
- background color:
projectdoc-bg-COLORNAME
This is an example to render a box with the colors White, DarkBlue an Darkorange:
projectdoc-section-box
projectdoc-h-White
projectdoc-c-DarkBlue
projectdoc-bg-Darkorange
Set the classes as value for the property "CSS Classes" of the Section Macro (or Content Marker Macro):
With this CSS Classes set, the section macro
is rendered as a box like this:
Example of a colored section
This is an example of a colored section.
- This is an example of a colored section.
- This is an example of a colored section.
Here is a list of all supported HTML color names for the CSS templates:
AliceBlue AntiqueWhite Aqua Beige Black BlanchedAlmond Blue BlueViolet Brown BurlyWood CadetBlue Chartreuse Chocolate Coral CornflowerBlue Cornsilk Crimson Cyan DarkBlue DarkCyan DarkGoldenRod DarkGray DarkGrey DarkGreen DarkKhaki DarkMagenta DarkOliveGreen Darkorange DarkOrchid DarkRed DarkSalmon DarkSeaGreen DarkSlateBlue DarkSlateGray DarkTurquoise DarkViolet DeepPink DeepSkyBlue DimGray DodgerBlue FireBrick FloralWhite ForestGreen Fuchsia Gainsboro GhostWhite Gold
GoldenRod Gray Grey Green GreenYellow HoneyDew HotPink IndianRed Indigo Ivory Khaki Lavender LavenderBlush LawnGreen LemonChiffon LightBlue LightCoral LightCyan LightGoldenRodYellow LightGray LightGrey LightGreen LightPink LightSalmon LightSeaGreen LightSkyBlue LightSlateGray LightSlateGrey LightSteelBlue LightYellow Lime LimeGreen Linen Magenta Maroon MediumAquaMarine MediumBlue MediumOrchid MediumPurple MediumSeaGreen MediumSlateBlue MediumSpringGreen MediumTurquoise MediumVioletRed MidnightBlue MintCream MistyRose
Moccasin NavajoWhite Navy OldLace Olive OliveDrab Orange OrangeRed Orchid PaleGoldenRod PaleGreen PaleTurquoise PaleVioletRed PapayaWhip PeachPuff Peru Pink Plum PowderBlue Purple Red RosyBrown RoyalBlue SaddleBrown Salmon SandyBrown SeaGreen SeaShell Sienna Silver SkyBlue SlateBlue SlateGray SlateGrey Snow SpringGreen SteelBlue Tan Teal Thistle Tomato Turquoise Violet Wheat White WhiteSmoke Yellow
Since 1.6
The parameter is supported since version 1.6.0.
Not that the enclosing HTML DIV element renders a CSS class that includes the identifier of the doctype. This allows users to render sections on different doctypes differently.
Since 2.0
Since 2.0 the enclosing HTML DIV element renders 'projectdoc-not-a-doctype
' instead of 'projectdoc-null
'.
Numbering
Switch on or off the numbering for the heading.
The property Enable Heading Numbers
is required to be set to true
on either document or space level.
The numbering is created with CSS. If the output format does not apply CSS styles, no numbers will be rendered.
For more information on how to control numbering in your projectdoc documents, refer to these space properties:
- Enable Heading Numbers - controls whether or not section headings should be numbered. The numbers are added via CSS, therefore they won't work for export formats that do not take CSS into account.
- Heading Max Numbered - controls the max depth to which headings are numbered.
- Heading Number Start - controls the start number of the first heading on a page.
- Heading Starting Level - controls the top heading level for a document.
- Suppress Heading Numbers on Doctypes - controls the suppression of heading numbers dependent on the doctype.
- Use Document Heading Number - controls whether or not the title of the document should have a heading number.
The parameter is supported since version 1.5.0.
Numbering Start
Specify the start of the first level numbering.
The parameter is supported since version 1.5.0.
Details
Author Support
For supporting authors with using transclusions, the macro renders the title for the heading with the section's id, tags and HTML anchor information (highlighting the header). Authors may use this information with the Transclusion Macro or reference the section from a remote page.
If the author sets the space property Pretend Being A
to true
, the help is not rendered.
Related Macros
Name | Short Description | Notes |
---|---|---|
Marks a piece of content within a document. This content can be referenced for transclusion. | Similar to the Section Macro, but without a title. | |
Transcludes content from a document marked with the content marker macro. | Transcludes content from this macro into another page. | |
Transcludes content via a reference from a document marked with the content marker macro. | Transcludes content from this macro via a property reference into another page. | |
Renders transcluded content fetched from documents of a result set. | Multi-transclusion of content from other pages. |
Resources
More information on sections in this manual.
- Section in Action
- Use the Section Macro to define sections. This tip introduces the macro by listing its features.
- The hidden Section
- The Content Marker Macro identifies content that can be displayed using the Display Table Macro. This is a short tip on how to transclude content from a projectdoc document.
- No need to render the Section Title
- It is often obvious that the introduction text is a description of the information of the document. Therefore the title 'Description' or 'Summary' may be irrelevant. You may suppress the rendering of the title easily.
- Documentation JSON URI
- The URI to a JSON document containing the URLs to the documentation for the blueprints.
- DocumentationMap
- Stores the documentation map to link to doctype documentation.