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

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 ö ä ü ß.

$
wget --http-user=admin --http-password=foobar  --output-document=my.config "http://confluence/plugins/servlet/advanced-codeblock-macro-downloadcode?pagepropertykey=dGVzdHN5c3RlbSAy&pageid=360457&macroid=640de3c7-bfbf-493a-a2d6-721ced07a0ef&os_authType=basic"

Specs Direct Download

EncodingUTF-8
Encoding with asciionly-modeASCII plus ä ö ü ß
Content-Typetext/plain
AuthentificationBasic Auth

HTTP Status Codes

HTTP 200Download possible.
HTTP 401Unauthorized. 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 403Forbidden. You do not have the view page permission right on the Confluence® Page in which the macro is embedded.
HTTP 500Internal 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&amp;pageid=360457&amp;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&amp;pageid=360457&amp;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&amp;pageid=360457&amp;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

EncodingUTF-8
Encoding with asciionly-modeASCII plus ä ö ü ß
Content-Typeapplication/xml
AuthentificationBasic Auth

HTTP Status Codes and Error Responses

HTTP 200XML 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 401Unauthorized. Not logged in to Confluence®.
<advancedCodeblockMacro>
  <error>401 UNAUTHORIZED</error>
  <message>no logged in user found</message>
</advancedCodeblockMacro>
HTTP 403Forbidden. 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 500Internal 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

HeadlineMyTestFile
URLhttp://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.