User Guide

To use the macros you need to be on a Confluence page in edit mode. Then you can click on + Insert macro content → ... other macros and if you then search for advanced codeblock you should see boths macros like so.

Classic Macro

Advanced Codeblock Macro

Enables you to provide different
permutations of a code by using placeholders.

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®

Select the Advanced Codeblock Macro from the Macro Browser and insert it into the page. The red error message you get in the preview is normal, since the macro-body is missing, which you will insert in the next step.

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

HTTP Status Codes

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

HTTP Status Codes and Error Responses

<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>

<advancedCodeblockMacro>
  <error>401 UNAUTHORIZED</error>
  <message>no logged in user found</message>
</advancedCodeblockMacro>

<advancedCodeblockMacro>
  <error>403 FORBIDDEN</error>
  <message>no read permission on page with id 1234</message>
</advancedCodeblockMacro>

<advancedCodeblockMacro>
  <error>500 ERROR</error>
  <message>Did you provide valid URL-Parameters?</message>
</advancedCodeblockMacro>

Remote Macro

Advanced Remote Codeblock Macro

Same as Advanced Codeblock
Macro but with using a remote file as base.

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

[foobar]
moo=wuff

What does it look like

This will produce the following result

In the macro footer you can click on the refresh cache button to trigger the download of the remote file.

Read Only Mode (Data Center)

Since v2.5.0 and for Confluence® Data Center versions higher or equal 6.10 we support the Confluence® Data Center Read Only Mode.

When the Read Only Mode is activated the Classic Macro will render with disabled direct download features, since they would perform a write operation on the page properties. There is a little message in the bottom right corner to indicate this.

The same convention applies for the Remote Macro. For the Remote Macros additionally the refresh-cache button is hidden.

If you for some reason call the refresh-button URL during enabled Read Only Mode you will see this page.