User Guide
Classic Macro
The Advanced Codeblock Macro offers you the possibility to provide different configurations (testsystem1, testsystem 2) based on one base-configuration (content).
Therefore placeholders are used. You can use a placeholder via ${placeholder_name} in the content. When the macro is rendered it will be replaced by the set value.
Inserting the macro in Confluence®
Example macro body
:
[testsystem 1] base.url = www.myserver1.com document.root = /www/server1 [testsystem 2] base.url = www.myserver1.com document.root = /www/server2 [content] <VirtualHost *:80> DocumentRoot ${document.root} ServerName ${base.url} ... </VirtualHost>
The example above needs to be used as macro body
Be sure to check for whitespaces beetween the INI-Blocks. There should be no whitespaces in the marked areas.
What does it look like
The macro then renders the following output:
Syntax-Highlighting
To use syntax-highlighting you can select a programming language in the edit macro
screen or just let the language be detected automatically.
Usage for the Direct Download Feature
The Direct Download Feature provides a way to directly download the configuration.
An administrator could download the configuration directly on a linux machine by using commands like wget or curl. To activate Direct Downloads you must check the checkbox when inserting the macro.
The Direct Download Link resides in the right upper corner of the every inner codebox. It allows you to download the code with replaced placeholders.
The Raw Download Link resides in the down right corner of the macro. It allows you to download the code with placeholders (no replacements).
The Download List Link resides in the down right corner of the macro. It allows you to view a xml of all download links of the macro. See Usage for the Download List Feature below.
You have to authenticate via Basic Auth
when downloading.
Example Direct Download
The following unix command demonstrates a Direct Download to a unix system.
The username for Confluence® is admin and the password foobar.
As outputfilename we choose my.config. You need to append &os_authType=basic
to the DDL-url to tell Confluence® that BasicAuth is used.
If you want to strip all possible bad chars like non-space utf-8 chars that break your apache virtualhost config, use &asciionly=true
which strips everything from your config except ASCII and ö ä ü ß.
Specs Direct Download
Encoding | UTF-8 |
---|---|
Encoding with asciionly-mode | ASCII plus ä ö ü ß |
Content-Type | text/plain |
Authentification | Basic Auth |
HTTP Status Codes
HTTP 200 | Download possible. |
---|---|
HTTP 401 | Unauthorized. Not logged in to Confluence®. (Please keep in mind that you will need to use a captcha once your authentication attemps fail to often) |
HTTP 403 | Forbidden. You do not have the view page permission right on the Confluence® Page in which the macro is embedded. |
HTTP 500 | Internal error. Wrong url-parameters, Confluence® page does not exist any more or any other error. Confluence® logs the exeption to the logfile. |
A Direct Download opens in a new window and looks like this:
Notice for using Direct Downloads
- By changing the
configname
(in the example testsystem 1) the download link changes! - The download link gets changed when the macro is moved to another page!
- The data is internally stored as content properties of the Confluence® page.
Usage for the Direct Download List Feature
You can click on the Download List Link to see a XML list of all downloadable links with human readable names.
For the example from avove the XML-List Output looks like this
<advancedCodeblockMacro>
<page>
<pageId>360457</pageId>
<pageName>Testpage</pageName>
<spaceKey>TEST</spaceKey>
<macroId>b77502b0-1dc4-4227-8c11-b03d9f581507</macroId>
</page>
<codeBlocks>
<codeBlock>
<key>dGVzdHN5c3RlbSAx</key>
<name>testsystem 1</name>
<download>http://localhost:8090/plugins/servlet/advanced-codeblock-macro-downloadcode?pagepropertykey=dGVzdHN5c3RlbSAx&pageid=360457&macroid=b77502b0-1dc4-4227-8c11-b03d9f581507</download>
</codeBlock>
<codeBlock>
<key>dGVzdHN5c3RlbSAy</key>
<name>testsystem 2</name>
<download>http://localhost:8090/plugins/servlet/advanced-codeblock-macro-downloadcode?pagepropertykey=dGVzdHN5c3RlbSAy&pageid=360457&macroid=b77502b0-1dc4-4227-8c11-b03d9f581507</download>
</codeBlock>
<codeBlock>
<key>cmF3</key>
<name>raw</name>
<download>http://localhost:8090/plugins/servlet/advanced-codeblock-macro-downloadcode?pagepropertykey=cmF3&pageid=360457&macroid=b77502b0-1dc4-4227-8c11-b03d9f581507</download>
</codeBlock>
</codeBlocks>
</advancedCodeblockMacro>
- The first pageproperty Block is for [testsystem 1]
- The second pageproperty Block is for [testsystem 2]
- The third pageproperty Block is for [raw]
- The servlet will list all download Links for one specific Advanced Codeblock Macro on the page.
Specs Direct Download List
Encoding | UTF-8 |
---|---|
Encoding with asciionly-mode | ASCII plus ä ö ü ß |
Content-Type | application/xml |
Authentification | Basic Auth |
HTTP Status Codes and Error Responses
HTTP 200 | XML with download links is displayed. | <advancedCodeblockMacro>
<page>
<pageId>360457</pageId>
<pageName>Testpage</pageName>
<spaceKey>TEST</spaceKey>
<macroId>b77502b0-1dc4-4227-8c11-b03d9f581507</macroId>
</page>
<codeBlocks>
<codeBlock>
<key>dGVzdHN5c3RlbSAx</key>
<name>testsystem 1</name>
<download>http://url....</download>
</codeBlock>
<codeBlock>
<key>dGVzdHN5c3RlbSAy</key>
<name>testsystem 2</name>
<download>http://url...</download>
</codeBlock>
<codeBlock>
<key>cmF3</key>
<name>raw</name>
<download>http://url...</download>
</codeBlock>
</codeBlocks>
</advancedCodeblockMacro> |
---|---|---|
HTTP 401 | Unauthorized. Not logged in to Confluence®. | <advancedCodeblockMacro>
<error>401 UNAUTHORIZED</error>
<message>no logged in user found</message>
</advancedCodeblockMacro> |
HTTP 403 | Forbidden. You do not have the view page permission right on the Confluence® Page in which the macro is embedded. | <advancedCodeblockMacro>
<error>403 FORBIDDEN</error>
<message>no read permission on page with id 1234</message>
</advancedCodeblockMacro> |
HTTP 500 | Internal error. Wrong url-parameters, Confluence® page does not exist any more or any other error. Confluence® logs the exeption to the logfile. | <advancedCodeblockMacro>
<error>500 ERROR</error>
<message>Did you provide valid URL-Parameters?</message>
</advancedCodeblockMacro> |
Remote Macro
This macro works the same way as the classic macro except that is has no macro body
and uses a remote file
instead.
Please read the documentation of the classic macro first.
Inserting the macro in Confluence®
Fill out the URL and other fields in the Macro Browser.
If your remotefile is password protected (Basic Auth) you can specify the http username and password.
Example
Headline | MyTestFile |
---|---|
URL | http://codeclou.io/test-advanced-codeblock-macro/v2.3/public/testfile.foo |
HTTP Username | - |
HTTP Password | - |
Programming language | - |
What does it look like
This will produce the following result
Note: In the macro footer you can click on the refresh cache button trigger the download of the remote file. Once downloaded it is cached until page save or changes to the macro.