- Created by Robert Reiner, last modified on 01. Jan 2020
projectdoc Toolbox
Transclude text content from a remote server.
- Categories
- Tags
- Type
- Extension
- Since
- 1.0
Transcludes a text snippet from a resource on a server.
The definition of the snippet is line based. Either there is a marker on a line or the line numbers are specified.
Including unknown text snippets inside a web page is dangerous!
Please be very careful when transcluding information from external servers!
Usually you should only transclude pages or parts of pages, if you also are in control of the contents. Transcluding arbitrary information my result in executing scripts on your server. A malicious attacker may steal other user's authentication cookie or do other harmful things!
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.
In contrast to the System Transclusion Macro, the Text Snippet Macro allows to specify the link to the resource directly and therefore does not provide system identifiers to define a space-wide base URL.
Properties
URL
The URL to the resource to transclude.
Snippet ID
The identifier of the snippet to include.
With the line after the line containing the identifier the snippet starts. The line marking the end of the snippet again includes this identifier (and this line is also not part of the snippet).
Example with Snippet ID
The example can be fetched with the ID 'important'.
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. [important] Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. [important] Nam liber tempor cum soluta nobis eleifend option congue nihil imperdiet doming id quod mazim placerat facer possim assum. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat.
Lines
The line or line ranges to match. There may be multiple line ranges, separated by comma.
Here are some examples:
| Specified | Description | |
|---|---|---|
-12 | Transclude all lines up to and including line 12. | |
23 | Transclude line 23 only. | |
42-50 | Transclude lines 42 to 50, both edge values included. | |
90- | Transclude from line 90 to the end of the file. | |
-12, 23, 42-50, 90- | All of the above in combination. |
Please note that this information is not used, if a snippet ID is provided.
Encoding
The encoding of the file. Defaults to the character type announced by the response.
Use extra Snippet Marker
Check if the extra labels "SNIPPET START" and "SNIPPET END" should assumed. This may help to make you snippet ID marker unique without having to add this identifier parts with the snippet ID explicitly.
Example with Snippet ID
The example can be fetched with the ID 'important', but makes it less likely to match an arbitrary string in the text..
Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. [SNIPPET START important] Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. [SNIPPET END important] Nam liber tempor cum soluta nobis eleifend option congue nihil imperdiet doming id quod mazim placerat facer possim assum. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat.
Plain
If unchecked, the snippet is rendered within the Code Block Macro (only then do the following code attributes apply). Otherwise it is rendered as plain text fragment.
Code Language
If the snippet is rendered not in plain text, this value is passed to the Code Block Macro.
The value "Default Language" refers to the value provided by the space property "Code Language".
Code Title
If the snippet is rendered not in plain text, this value is passed to the Code Block Macro.
Code Theme
If the snippet is rendered not in plain text, this value is passed to the Code Block Macro.
Code Line Numbers
If the snippet is rendered not in plain text, this value is passed to the Code Block Macro.
Code First Line
If the snippet is rendered not in plain text, this value is passed to the Code Block Macro.
Code Collapse
If the snippet is rendered not in plain text, this value is passed to the Code Block Macro.
Details
Error Messages
If the macro cannot find the snippet to transclude, an error message is displayed.
If you encounter a 200: OK message, the files has been found on the remote server, but the snippet to transclude cannot be determined. Please check the spelling of your snippet ID and also check if Use extra Snippet Marker is checked.
If the result is a 404, the specified file cannot be found to transclude from.
Authentication
Since version 1.4 of the Information Systems Extension the autoconverter service and transclusion macros (System Transclusion Macro, Text Snippet Macro, and HTML Snippet Macro) use the Application Links configured in Confluence to access remote resources.
The following authentication methods are supported:
- Impersonating OAuth (recommended)
- Basic Authentication (useful for non-Atlassian servers that do not provided OAuth)
Prior to version 1.4 the macro does not provided means to access resources that are protected by a password.
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.
- Hudson Link Macro
- Render links to jobs and services on a Hudson 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.
- 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.
