projectdoc Toolbox

Transclude content from a resource from a remote system.

Categories

Link / Information System

Tags

Type

Content Reuse

Extension

Information Systems Extension

Since

1.0

Transcludes a snippet from a project on a server.

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.

Properties

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 '<system-id>' 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-<system-id>
Check for a space property <system-id>
Only available with projectdoc Toolbox version 1.11 and up!
Check for a space property shortcut-id-<system-id>.
Lookup the connection information from the shortcut links with the value retrieved from the space property.
Check the shortcut links for a value <system-id>.
Check application navigator for a value <system-id>.

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 transclude from.

If the resource cannot be found on the remote server, a warning box is rendered.

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.

Snippet ID Query

If checked, the Snippet ID is considered to be a query selector.

The selector is required to specify an HTML element. Introduce the selector with '#' to specify the unique identifier of an HTML element.

Use jsoup's Selector Syntax to specify queries. The first element in the result set is transcluded content.

One-time Transclusion?

If you do not want to specify a system, e.g. you are only transcluding from a system on one occasion, have a look at the HTML Snippet Macro.

Available since version 1.1.

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.