projectdoc Toolbox

Allows to render a link to a wiki page.

Audience

Documentation Architect, Template Author

Categories

Tags

Renders a link to a page in the wiki. It uses the delegate space or the search space for searching the page with the specified title.

This macro is usually relevant for template authors and documentation architects. It allows to reference the home page of a document type, without knowing exactly, where it is located.

Example with 4 different Link Styles

All four link styles are automatically generated, dependent on the location or existence of the target page within the wiki.

The Wiki Link Macro is replace by macros that have only a selected number of its responsibilities. This should make the use of links for users much more easier.

Please pick the suitable replacement for the Wiki Link Macro from the following list.

#	Name	Short Description
1	Static Document Link Macro	Renders a static link to a projectdoc document in the wiki. A static link is a link to a Confluence page that is identified by its space key and document title.
2	Dynamic Document Link Macro	Renders a dynamic link to a projectdoc document in the wiki. A dynamic link is a link to a Confluence page that is identified by the page title and the delegate space closure. The target of the link is calculated at render time. In case the delegate space closure changes, a different document may be the target of the link.
3	In-Document Link Macro	Renders a static link to a location within the same document. This is a static document link macro with a specialized interface.
4	Template Document Link Macro	Allows to render a link constructed with a template to a document dependent on the space closure.
5	Term Link Macro	Renders a dynamic link to a Glossary Item in the wiki.

Properties

Space Key

The key to the space the page is part of. If empty, the macro tries to find a page with the given page title on the delegate space.

Document

The title of the document to link to.

Overrides the page parameter.

Since version 4.5 this parameter may have no or the value @self. In this case the Wiki Link Macro renders a reference to the current page.

This is required by use cases where remote control is configured and should render an alternate view on the current page.

Anchor

The Anchor allows to define a page fragment to reference on the target page.

Since 4.5

The parameter is available since version 4.5 of the projectdoc Toolbox.

The anchor value may have one of two forms:

If the first character is a hashmark (#), then the anchor is used verbatim as fragment part of the generated URL
If the first character is not a hashmark (#), then the anchor is a section title and a proper anchor is derived

So if the reference is to a section using the Section Macro, simply add the title of the section. If the user knows the identifier or anchor in the HTML code, use that identifier an put a hashmark (#) in front.

Valid values: Section Titles and Identifiers

My Section Title
#my-element-id
#myAnchorName

Label

The label to render instead of the page name.

If neither the document or page parameter is set, the label is used as a the page title.

Since 4.6

Since version 4.6 the label supports templates. It may contain property placeholders (like ${Title}) of the referenced document.

Note that the whole label is rendered as a link. Placeholders rendering links are not supported as well as placeholders that support rendering the property as HTML. In case you need to control which part of the label actually contains a link, please use the Display Document Properties Macro.

Lower Case

When checked the label of the link is rendered in lower case.

This is especially useful for text in the English locale to appear in the body of a section.

Since 4.6

This parameter is supported since version 4.6.

CSS Classes

The optional CSS classes to add to the link.

Automatic Classes

If the page is not located in this space, the CSS class projectdoc-space-reference is added automatically (see Render Space Style).
If it points to a home page of a doctype without an index page, the class projectdoc-no-docs is added automatically (see Render No Docs Style).

Space Closure

The space closure defines which spaces are to be considered for searching.

Valid values are

space-default
delegate-space
search-space
self-space (since 4.5)

Per default the delegate spaces are used. This is what the is most often needed: the location where new documents are stored per default is the location this macro will link to.

If you have a space that references the latest version of a product space, you may want to link to information to be found in any space. In this case the space contains the latest version of a space in its search space. Using this link will ensure that the latest version is linked.

The value self-space restricts the search to the local space, that is the space the the page with the macro is part of. This supports the use case where the template authors want to limit the search.

Since 3.1

Since version 3.1 the default checks the space property Default Space Closure for the default space closure. If this space property is not set, the default is still Delegate Space.

Doctype Constraints

Referenced documents must match the doctype provided by this parameter to be considered a valid link target.

If a document does not meet the constraints or is not a projectdoc document, it is skipped while traversing the space closure (including the current space).

Since 4.9

The parameter is available since version 4.9 of the projectdoc Toolbox.

Render No Docs Style

Signal no existing docs in this space visually.

The projectdoc space renders homepages for doctypes. This flag checks if there is an index page for a given doctype.

Uncheck to suppress rendering the CSS style projectdoc-no-docs.

See Doctype Instances Localization Mode for controlling the search mode for determining the existence of documents of a given type.

Since version 1.10.

Render Space Style

Signal space reference visually.

Uncheck to suppress rendering the CSS style projectdoc-space-reference.

Since version 1.10.

Link Render Control

Control how the link is rendered if the target document does not exist.

Valid values are:

create-link: Render a link to create a document (default)
empty: Render nothing
plain-text: Render the link label.

Since 1.10

The parameter is supported since version 1.10.

Empty if not exists

Deprecated since version 1.10. Use Link Render Control with a value of empty instead.

If checked, the link text will not be rendered, if the target page within the wiki does not exist.

Plain text if not exists

Deprecated since version 1.10. Use Link Render Control with a value of plain-text instead.

If checked, the link text will be rendered as plain text, if the target page within the wiki does not exist.

If the option "Empty if not exists" is selected, the text will not shown. That is: this option is overridden by the empty text option.

Abbreviation Mode

Renders the abbreviation or short name with the name as tooltip.

The following options are available:

Option	Description
`none`	Does not activate the abbreviation mode. The link uses the name to render the label and the document's short description as tooltip.
`name`	Renders the abbreviation or short name as label and the document's name as tooltip.
`short-name`	Renders the abbreviation or short name as label and the document's short name as tooltip.

Since 4.6

The parameter is supported since version 4.6.

Blueprint

The complete key of the page blueprint.

A page blueprint key looks like this:

de.smartics.atlassian.confluence.smartics-projectdoc-confluence:projectdoc-blueprint-doctype-blank

This example refers to the Blank Document.

If omitted, the new page will be based on the empty page template.

Request Parameters

Request parameters allow to call a Remote Controlled Document (e.g. using the Display Table Macro).

Available since version 2.4.

The left side (value) of the parameter assignments will be URL encoded. The expected pattern is

id-x:name1=value A, value B&id-y:$<name2>=[some value]

Remote Controller

This macro passes the Remote Controls via HTTP request parameters. Other Remote Controllers do this via macro parameters set in the rendering context.

Request Toggle Label

In case the macro adds request parameters it is able to react to a request that contains these request parameters with matching values. In case the macro is called on a page with its request parameters it will render the provided label and will not add its request parameter. This effectively allows the macro to toggle between two states: one in which the macro applies the request parameters and uses its standard label and one in which the request parameters are not applied and the toggle label is used.

Since 4.5

This parameter is available since version 4.5 of the projectdoc Toolbox.

Request Toggle Tooltip

Set the tooltip for the link when in the toggled state. This tooltip is only shown with the Request Toggle Label.

If the toggle state for Remote Control is not in use, this parameter has no effect. To enforce this feature the Request Parameters and the Request Toggle Label must be specified. Whenever the macro recognizes that its request parameters are set, it enters the toggle state.

Since 4.5

This parameter is available since version 4.5 of the projectdoc Toolbox.

Page

The name of the page to link to.

For template developers: This may be the key to the localized information. This is useful if you create blueprint projects with space blueprints.

The name may contain placeholders that are replaced by document or space properties.

The name may also contain special placeholder values that will be replaced:

Placeholder	Description
`@parentPageTitle`	If the page has a parent page, the placeholder is replace with that page's title.
`@spaceKey`	The placeholder is replaced with the page's space key.
`@spaceName`	The placeholder is replaced with the page's space name.
/	Signals to link to the space homepage.

Placeholders referencing the current date or time are not supported.

If template authors want to reference the parent page of a Section document instance, they use the following:

<ac:structured-macro ac:name="projectdoc-link-wiki">
  <ac:parameter ac:name="page"><at:i18n at:key="my.page.name.i18n.key"/> - @parentPageTitle</ac:parameter>
</ac:structured-macro>

Since version 4.5 this parameter may have no or the value @self. In this case the Wiki Link Macro renders a reference to the current page (if also the Document Parameter is blank).

This is required by use cases where remote control is configured and should render an alternate view on the current page.

Related macros

Breadcrumb Macro: Renders a breadcrumb for the current page.
Child Documents Macro: Renders the list of child documents, matching the given filter criteria.
Cite Macro: Renders a cite to a resource document.
Create One Document Macro: Renders template button to create a page. After the page is created, the macro renders a link to this page.
Enterprise Architect Image Link Macro: Renders an image generated from an Enterprise Architect diagram, transcluded from a server.
External Link Macro: Renders a locale dependent link to an external resource. The body of the macro contains the link label.
HTML Snippet Macro: Transclude HTML content from a remote server.
Hudson Link Macro: Render links to jobs and services on a Hudson server.
Javadoc Link Macro: Links API documentation pages for Java elements.
Name Body List Macro: Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name hat is added to the body.
Name List Macro: Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name.
Nexus Link Macro: Renders a link to an artifact stored on a Nexus server.
Parent Property Macro: Renders the property of the parent document, if it has the same doctype.
Role List Macro: Renders a name list while taking care of special role semantics. Confluence names of groups with view permissions are added to the list of values.
Site Link Macro: Links to a resource on a versioned site.
Sonar Link Macro: Renders a link to a project on a Sonar service.
Subversion Link Macro: Renders a link to a resource on a Subversion (SVN) repository.
Subversion Transclusion Macro: Transcludes a snippet from a project on a Subversion (SVN) server.
System Image Link Macro: Renders an image transcluded from a remote server.
System Link Macro: Links to a resource on a server.
System Transclusion Macro: Transclude content from a resource from a remote system.
Tag Body List Macro: Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name hat is added to the body.
Tag List Macro: Renders a name list while taking care of special tag semantics. Confluence labels are added virtually to this list and displayed in the tags table row of the document properties table.
Text Snippet Macro: Transclude text content from a remote server.

Resources

Linking to Glossary Terms: Show how to use the Name List Macro to render links to glossary terms.
Doctype Instances Localization Mode: Controls how document instances are located in a space.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Properties

Space Key

Document

Anchor

Label

Lower Case

Tooltip

CSS Classes

Automatic Classes

Space Closure

Doctype Constraints

Render No Docs Style

Render Space Style

Link Render Control

Empty if not exists

Plain text if not exists

Abbreviation Mode

Blueprint

Request Parameters

Request Toggle Label

Request Toggle Tooltip

Page

Related macros

Resources

About

Keep up-to-date!

Powered by