projectdoc Toolbox

Links to a resource on a server.

Categories

Tags

Extension

Since

1.0

The System Link Macro allows to render a link to a resource on a remote server. The system is identified via Confluence shortcuts or space properties.

Since projectdoc Toolbox version 1.11 this macro is part of the Information Systems Extension. Prior to that version the macro has been part of the projectdoc Toolbox.

The Since attribute above refers to the version of the extension, not to the version of the projectdoc Toolbox.

Properties

Label

The label for the link. Defaults to the name of the file - and if not given - the identifier of the system.

The value may contains property placeholders.

System Identifier

Identifies the connection information via Confluence shortcuts or space properties.

The system identifier is checked at three locations

Typically do not change the system identifier provided by the macro (if one is specified). Keep the default value of ' ' as long as you do not need to reference multiple server of the same type in one space. Then set the space property to reference the specific server accordingly. This makes it easier to create new links to artifacts since the system identifier need not to be changed.

The search for the system connection information is conducted as follows. Use the URI discovered first to connect to the server.

Check for a space property url-
Check for a space property
Only available with projectdoc Toolbox version 1.11 and up!
Check for a space property shortcut-id- .
Lookup the connection information from the shortcut links with the value retrieved from the space property.
Check the shortcut links for a value .
Check application navigator for a value .

If no value is specified at any of the locations above, the macro renders an error message like this:

In this example for a system macro the referenced, but undefined system, is called test-repo.

The system identifier is added as CSS class to the link element.

System Type

Identifies the type of system referenced.

If no system identifier is specified, the system type is used as default. If no predefined system type is applicable, use generic.

The system type is added as CSS class to the link element.

Since version 1.0.

File

The file on the server to link to.

The value may contains property placeholders.

Control with the Check Resource parameter, how the macro should signal a missing resource.

Delimiter

The delimiter to check in case the file is appended. If the delimiter is neither the last character of the system URL nor the first character of the file then this delimiter is inserted between the system URL and file name.

The delimiter is required to be one character. If more characters are specified, for instance none, then no delimiter will be inserted.

If no value is specified, the default delimiter is '/'.

Since 3.4

Available since version 3.4 of the Information Systems Extension.

Apply Space Properties

If checked the properties defined by the space of the document this macro is part of are applied as defaults.

Render Full URL

If checked and no label specified the URL is rendered in full.

Check Resource

If checked, the resource the URL points to is checked for existence.

Dependent on whether the resource exists or not a CSS class is added.

CSS Class	Status
`projectdoc-resource-exists`	Resource exists
`projectdoc-resource-not-exists`	Resource does not exist

Note that the check does not use any application link configuration (available since version 1.4). The autoconvert service does. Hence a link macro may show the title of the referenced page as a label, but still is a dead link for users with insufficient privileges.

Details

Autoconvert

To create the macro authors may simply paste the URI to the resource to the editor.

All is needed is a configuration of the resource repository base URI. For more information on this topic, please refer to Autoconvert Information System URIs.

Labels for the generated link may be determined correctly (i.e. will show the title of the page) even if the page needs authentication to be accessed. See Authentication for details.

In case you need to use the macro on URLs pointing to the Confluence instance, you should use the tiny URLs. Otherwise (usually) the Confluence built-in autoconverter will take priority in converting the link.

You can determine the tiny URL easily by typing 'k' in the view mode of a page.

Related macros

The following macros help with referencing resources on other information servers:

Enterprise Architect Image Link Macro: Renders an image generated from an Enterprise Architect diagram, transcluded from a server.
HTML Snippet Macro: Transclude HTML content from a remote server.
Javadoc Link Macro: Links API documentation pages for Java elements.
Nexus Link Macro: Renders a link to an artifact stored on a Nexus server.
System Image Link Macro: Renders an image transcluded from a remote server.
System Transclusion Macro: Transclude content from a resource from a remote system.
Text Snippet Macro: Transclude text content from a remote server.

Resources

Confluence as the Information Hub: Tools from the projectdoc Toolbox to import from and export to other information systems.

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