- Created by Robert Reiner, last modified on 23. Jul 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 17 Next »
projectdoc Toolbox
Marks a piece of content within a document. This content can be referenced for transclusion.
- Audience
- Categories
- Tags
- Type
The macro allows to mark content to be selectable for transclusion. It also allows to hide the content on given constraints.
Properties
Identifier
The identifier uniquely identifies the content within the document. An HTML element will be rendered with that id as an attribute.
Tags
Allows to tag the content for transclusion with the Transclusion Macro. You may specify more than one tag in this comma separated list.
Hide
The flag allows to not render the content, if checked. Use this parameter to temporarily hide content from being show to readers.
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.
Since 3.0
This parameter is available since version 3.0.
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.
Since 4.5
This parameter is available since version 4.5 of the projectdoc Toolbox.
Empty Block Text
The block is considered empty if the text matches the content.
Note that only content rendered on the server side is considered. If the content is altered by a JavaScript on the client side, this parameter has no effect.
Since 4.7
This parameter is available since version 4.7 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.
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. |
Since version 1.7.1 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.
Available since version 1.10.
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.
Since 2.1.4
Since version 2.1.4 it is possible to check for a certain property value.
property-name=my-value,!property-name2=other-value
Since 3.1
Since version 3.1 it is possible to check for rendered values.
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.
Available since version 1.1.8.
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.
Since 1.8
Since version 1.8 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.
Since 3.1
Since version 3.1 it is possible to check for rendered values.
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.
CSS Classes
Specify the CSS classes to be attached to the div
element (HTML) around the marked content.
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
The parameter is supported since version 1.6.0.
Wrapping Element
Specify the HTML element to enclose the content rendered by this macro.
Force First Child
Check to prevent the content being considered to be the first child.
This is a workaround for authors who need to force the contents of this macro not to be the first child in a container.
The parameter may be set to a value of true
as a page or space property by the name projectdoc.fix.content-marker.firstChild
.
Experimental Feature
This feature is available with version 4.2 of the projectdoc Toolbox.
It is considered to be experimental and may be removed in future versions.
Details
Author Support
For supporting authors with using transclusions, the macro renders the title of the body content with the section's id and tags (highlighting the text block). Authors may use this information with the Transclusion Macro.
If the author sets the space property
Pretend Being A
to true
, the help is not rendered.
Related macros
Name | Short Description | Notes |
---|---|---|
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. | Similar to the Content Marker Macro, but also allows to render a section header. | |
Transcludes content from a document marked with the content marker macro. | Transcludes content from this macro into another page. |
- No labels