- Created by Robert Reiner, last modified on 13. Aug 2017
projectdoc Toolbox
The Information Systems Extension for the projectdoc Toolbox allows to render a link with the HTML title as label via autoconvert of the pasted URL.
- Parent
- Audience
- Level of Experience
- Expected Duration
- 20 min
- Type
Pasting an URL to a Confluence page renders a representation that is clickable. If the URL points to an issue on a connected JIRA instance, this link is automatically converted to a macro that links to the issue. The feature responsible for this is Autoconvert for pasted Links.
The Information Systems Extension for the projectdoc Toolbox also provides autoconverters. Once an URL to a resource that is configured is pasted to a Confluence page, this URL is autoconverted to a projectdoc macro.
Link Text
One advantage is that the extension will fetch the page and render the title (HTML title or DC.title - if present) of the referenced document as label to the link.
Source Code
Rendered
Source Code
Rendered
The title information is fetched from the page the URL is linking to.
Dublin Core for Confluence?
If you want to add Dublin Core or other metadata to your Confluence pages, have a look at Add HTML Meta Tags.
Base Link
The main purpose for autoconverting a link to a macro is to make moving servers much more easy. If you are working with information systems in a team and write documentation that heavily links to these systems, changing the location may be a major pain for updating all links in your Confluence instance.
DNS anyone?
This problem can be easily removed by employing a Domain Name System or DNS, but our experience is that often teams do not provide such a system for their internal, often ad-hoc installed infrastructure.
Specific Information Systems
The Information Systems Extension for the projectdoc Toolbox also provides special treatment for specific information systems.
Here is a list of all macros used to link to or transclude from remote servers.
# | Name | Short Description |
---|---|---|
1 | Enterprise Architect Image Link Macro | Renders an image generated from an Enterprise Architect diagram, transcluded from a server. |
2 | HTML Snippet Macro | Transclude HTML content from a remote server. |
3 | Javadoc Link Macro | Links API documentation pages for Java elements. |
4 | Nexus Link Macro | Renders a link to an artifact stored on a Nexus server. |
5 | System Image Link Macro | Renders an image transcluded from a remote server. |
6 | System Link Macro | Links to a resource on a server. |
7 | System Transclusion Macro | Transclude content from a resource from a remote system. |
8 | Text Snippet Macro | Transclude text content from a remote server. |
How to use?
Required Add-ons
If you want to use this feature in your Confluence instance, you need to install the following add-ons.
The online manual for version 1 of the projectdoc Toolbox for Confluence. | ||
Add-on to extend the projectdoc Toolbox to integrate remote information systems. |
Configuration
You need to specify the remote information systems you want to enable autoconvert as space properties.
For this example we assume that autoconvert should be enabled for Wikipedia.
Navigate to a space home page where you want to enable autoconvert.
Use the Index Space
Since this is often a site-wide decision, consider to set the properties in the index space.
Note that the Delegate Space property allows to define parent pages where the index space the the root of all spaces.
To add a remote server add the url-wikipedia-en
space property.
This introduces the information system wikipedia-en
(without the url-
prefix) and specifies the root URL to the information system (which may or may not be a link by itself).
Not every URL you specify should be considered for autoconverting. Therefore you need to inform projectdoc that this new URL is actually to be a base URL for autoconverting by the use of the space property
Autoconvert Hint
.
Multiple values are separated by comma. Note that you specify the system ID wikipedia-en
you specified in the previous step. Also note that projectdoc needs to know how information is autoconverted. In our case it is linking, therefore we add ":link
".
Paste an URL to a page on Wikipedia in edit mode of a page in your Confluence and check that your configuration is correct!
Note that property names and values need to be free of any additional HTML envelopes! If you copy & paste values from an HTML page, there may be additional div or span elements around those values.
If you think everything should be all right, have a look at the page with the Confluence Source Editor or delete the lines and type them manually (without copy & paste).
For more information on this topic, please refer to Cannot access Property from a Document.