Basics

Learn about the terms that are used in this documentation and get an overview about the common basics of the Advanced Codeblocks and the Advanced Codeblocks Remote.

User Interface Components

The Advanced Codeblocks user interface is composed of the following components:

  1. codebox

  2. codebox title

  3. menu with contained download links and help

  4. codeblock with codeblock header and codeblock body

  5. download codeblock button

  6. detected programming language and copy to clipboard

When editing a page, the Advanced Codeblocks interface changes like so:

  1. macro name and parameters

  2. macro body

Terms

The Terms describe the different parts of your Advanced Codeblocks input. Your input is always compound of a config-block and a template.

config-block

A config-block contains your configuration. It is written in the INI file format and has to be defined in the macro-body. Be sure to check for whitespaces beetween the INI-Blocks - there should be no whitespaces.

section

[section]

A config-block contains one or multiple sections. Every section represents one codeblock and could get an arbitrarily name. The section name appears on a line by itself in square brackets.

key

name = value

A section contains one or multiple keys. Every key has a name and a value, delimited by an equals sign. The name can be used as the variable ${name} in your template. The value is the expression that will replace your variable.

content

content

A template will be initiated with the content term. The content term appears on a line by itself in square brackets and may not be renamed. If you use the Advanced Codeblocks Remote, you can leave it off.

template

A template contains the content for your codeblocks. Write your template in any preferred programming language. Insert your template directly in Confluence or load your remote template from any source.

variable

${name}

A variable is a placeholder in your template that will output the values you define in the keys of your config-block. The variable is composed of a dollar sign $ and the name of your key in curly brackets. Feed your template with as much variables as you want to enter repeating code with different values.

Your complete input could look like so:

[section 1]
name1 = value1
name2 = value2
[section 2]
name1 = value3
name2 = value4

[content]
 code
   ${name1}
   ${name2}
 code

Syntax highlighting

To enforce syntax highlighting for a specific language, switch to the edit mode of the app and choose your language from over 150 different programming languages.

Otherwise the language will be auto-detected. The selected language will be displayed when you hover the mouse over the codeblock body. In case that the auto-detection fails, you can enforce the correct syntax highlighting like described above.

Themes

The Advanced Codeblocks provides four different themes for a nice readable code. The default Theme is light-spring. If you prefer a colorful dark mode or a colorless variant, switch to the edit mode of the app and choose your preferred theme. Note that the same theme could differ slightly in different languages. The overview below is made with an Apache example:

light-spring

dark-spring

light-mono

dark-mono

Troubleshooting

You might get errors when your input is incorrect, the remote file is too large or your license is expired. An error will look like so:

To fix the error state of the Advanced Codeblocks for Confluence as soon as possible, every error has an error code at the bottom right corner. Please have a look at your appearing error code in the table below to get back on track. An error code for the Advanced Codeblocks looks like AC0001, for the Advanced Codeblocks Remote like ACR0001 and for license errors you get an expression like EXPIRED.

Error Codes and Description

0001
Filesystem Error

There was an unexpected filesystem error.

Cause

This error means that something went wrong with the underlying filesystem. Often this is caused by downloading a file that is too large or any other unexpected error regarding the file system of the Confluence Server.

Solution

Check the following:

  • Is the remote file you are trying to use larger than 2MB? Files must be smaller than 2MB.

0002
Formatting syntax error

You are using an invalid formatting / syntax.

Cause

This error means that your input code is not written in the expectedly syntax.

Solution

Check your input of:

  • Are whitespaces beetween the INI-Blocks? There should be no whitespaces.

  • Does every section and the content appear on a line by itself?

  • Are your sections and the content bracketed in square brackets?

  • Have you named the content [content]?

0003
Invalid URL

The URL to the remote file is not valid.

Cause

This error means that the remote url you are using is not valid.

Solution

Check the URL you are using. You could enter the URL directly in the browser to see if you can navigate to the desired file. Maybe there are some special chars that need to be URL Encoded, whitespaces or any other invalid characters.

0004
Download Error

There has been an error downloading the file.

Cause

This error means that while downloading the remote file an HTTP Error occured.

Solution

Check the following cases:

  • If HTTP 403: You entered correct Username and Password

  • If HTTP 401: The file is protected by Basic Auth and you need to enter Username and Password for downloading.

  • If HTTP 404: The URL of the remote file leads to a non existing file.

  • If HEAD Request error: Make sure that the Server that hosts your remote file does support HTTP HEAD requests.

0006
Empty macro body

Feed the Advanced Codeblocks with content! To see the preview the app needs content.

Cause

This info appears if the macro body has not already inserted content.

Solution

Insert content in the macro body.

EXPIRED
Invalid license

Your evaluation license of Advanced Codeblocks for Confluence expired. Please use the 'Buy' button to purchase a new license.

Cause

A license is invalid if the current date is greater than or equal to the license's expiration date.

Solution

Please use the 'Buy' button to purchase a new license.

TYPE_MISMATCH
Invalid license

Your evaluation license of Advanced Codeblocks for Confluence expired. Please use the 'Buy' button to purchase a new license.

Cause

A license is invalid if its type (commercial, developer, academic, etc.) is incompatible with the type of the application license.

Solution

Please use the 'Buy' button to purchase a new license.

USER_MISMATCH
Invalid license

Your Advanced Codeblocks for Confluence is only licensed for ... users. Your ... installation requires a license for ... users. Please get a Advanced Codeblocks for Confluence license for ... users and try again.

Cause

A license is invalid if its maximum number of users property is less than that of the application license.

Solution

Please use the 'Buy' button to purchase a new license.

VERSION_MISMATCH
Invalid license

Your license for maintenance of Advanced Codeblocks for Confluence is not valid for version X.Y.Z. Please use the 'Renew' button to renew your Advanced Codeblocks for Confluence license.

Cause

A license is invalid if the app's build date is greater than or equal to the license's maintenance expiration date.

Solution

Please use the 'Renew' button to renew your license.

If you are lost after all, issue a request in the codeclou Service Desk.

HTTP REST API

The REST API documentation describes the usage of the Download Feature to download configs directly from Confluence in your automated provisioning scripts with e.g. curl or wget. All Endpoints can only be accessed by an authenticated Confluence User that has the Page View Permission of the page the codebox is embedded in. Authentication can be done via Basic Auth.

Download the codeblock or raw template

The Endpoint let's you download a specific codeblock as plain text.

GET /plugins/servlet/advanced-codeblock-macro-downloadcode

Request Parameter

pagepropertykey
string

A code to identify the actual codeblock of the codebox. It is the BASE64 encoded version of the section name. Use cmF3 to download the raw template.
Example: dGVzdHN5c3RlbSAx

macroid
int

An unique ID generated by Confluence for the macro.
Example: 1213344

pageid
int

The ID of the Confluence Page the macro is embedded in.
Example: 234324

os_authType
string

Optional. Set this to 'basic' if you want to authenticate via Basic Auth.
Example: basic

asciionly
boolean

Optional. Set this to 'true' if you want to have all non-ASCII chars removed from the response body. This will retain ASCII and [öäüß].
Example: true

Request Example

$
curl https://my.confluence/plugins/servlet/advanced-codeblock-macro-downloadcode \
-G -u admin:admin \
-d pagepropertykey=cmF3 \
-d macroid=95b26f2e-4768-4e66-952e-37a8b56bcac1 \
-d pageid=1703938 \
-d os_authType=basic

Response Codes

200
OK

Download possible Response Body will contain the codeblock as plain text.

401
Unauthorized

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)

403
Forbidden

Forbidden You do not have the view page permission right on the Confluence Page in which the macro is embedded.

500
Internal error

Internal error Wrong URL-parameters, Confluence page does not exist any more or any other error. Confluence logs the exeption to the logfile.

Response Body

Encoding

UTF-8

Content-Type

text/plain

Response Body Example

<VirtualHost *:80>
  DocumentRoot /var/www/server1
  ServerName www.server1.com
</VirtualHost>

Download xml list

The Endpoint lists all download links for one specific codebox as XML.

GET /plugins/servlet/advanced-codeblock-macro-downloadlist

Request Parameter

macroid
int

An unique ID generated by Confluence for the macro.
Example: 1213344

pageid
int

The ID of the Confluence Page the macro is embedded in.
Example: 234324

os_authType
string

Optional. Set this to 'basic' if you want to authenticate via Basic Auth.
Example: basic

asciionly
boolean

Optional. Set this to 'true' if you want to have all non-ASCII chars removed from the response body. This will retain ASCII and [öäüß].
Example: true

Request Example

$
curl https://my.confluence/plugins/servlet/advanced-codeblock-macro-downloadlist \
-G -u admin:admin \
-d macroid=b77502b0-1dc4-4227-8c11-b03d9f581507 \
-d pageid=360457 \
-d os_authType=basic

Response Codes

200
OK

Download possible Response Body will contain the downloadlist as XML.

<advancedCodeblockMacro>
  <!-- See full example below -->
</advancedCodeblockMacro>

401
Unauthorized

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)

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

403
Forbidden

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>

500
Internal error

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>

Response Body

Encoding

UTF-8

Content-Type

application/xml

Response Body Example

  1. The first codeblock is for [testsystem 1]

  2. The second codeblock is for [testsystem 2]

  3. The third codeblock is for [raw]

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