General third-party app implementation

When using third-party add-ons either provided by Confluence or other vendors, there are sometimes a few more steps to implement, in order to make it work.

The following list will grow over time - if there's any third-party you want to integrate, please get in touch with us. We'll be happy to extend the information on this page.

Since the implementations of Scroll Viewport vary a lot, I'll try to point to the various places where to adjust the code or add something. Usually, you want to apply the code to the page.vm file. If you use dedicated files for another contexts, you can add it there too or use a shared template to include in each of these pages.

Add-Ons

Confluence Team Calendar

Add-on: Team Calendars for Confluence

Problem: Calendar items are not loading, creating new events does not work

Solution: The add-on relies on meta data remote-user in order to know for which user to show the calendar. Just add the following line within your <head> to fix the problem:

CODE

<meta name="ajs-remote-user" content="$user.username">
<meta name="ajs-space-key" content="$repository.key">

Page Properties Report

Add-on: Page Properties Report

Problem: Error message: Error while fetching page properties report data: Bad Request

Solution: The add-on relies on meta data ajs-space-key in order to know where the call originates from. Just add the following line within your <head> to fix the problem:

CODE

<meta name="ajs-space-key" content="$repository.key">

Code Block Macro

Add-on: Code Macro Plugin

Problem: Expanding/Collapsing the code does not work

Solution: The add-on relies on a container with the id "content". Which is present in Confluence but not in Viewport. Either add the id to the main content container or simply add it to the body:

CODE

<body id="content">

Additionally, we need to load the resources to initialize the functionality for expanding/collapsing the code block. Add this code to <head> section of the Viewport theme.

CODE

$page.resources.require('com.atlassian.confluence.ext.newcode-macro-plugin:syntaxhighlighter-init')

Viewport Tabs Macro

Add-on: Scroll Viewport

Problem: Switching tabs does not work

Solution: The macro relies on the default AUI resources.

Add this to your <head>.

CODE

$page.resources.css
$page.resources.js
$page.resources.meta

Adaptavist Ratings macro

Add-on: Adaptavist Rate macro

Problem: Anonymous users get an endless spinner when rating a page.

Solution: The add-on relies on session data only created on the specific Confluence page. We can't reproduce or recreate that session with client-side cookies alone. Which is why we need to send an AJAX request to a Confluence page, that contains a rate macro. This way, the required session data is created and rating works on Viewport. This solution is based on jQuery.

The Confluence page has to be publicly viewable (so no redirection for that space enabled). If you need to redirect users to the viewport, you can create a second space with the rate macro and use that url to load the session.

Put this script somewhere in your page.vm after loading jQuery.

CODE

<script>
jQuery.get('https://my-confluence.com/display/test/rate')
</script>

Expando

Add-on: Expando

Problem: The expando macro does unfold its contents when being clicked.

Solution: The add-on relies on a class called "wiki-content". Wrapping your $page.content with a div with the class will fix the problem.

CODE

<div class="wiki-content">
$page.content
</div>

Additionally, the resources have to be loaded. Add this to your <head>.

CODE

$page.resources.require('com.k15t.confluence.k15t-expando:expando-resources')

Finding a fix on your own

If the add-on is not listed in the above list yet, you can fix it on your own.

Most often, it is not that hard to amend the missing functionality. Sometimes, the macros rely on some meta data, that is usually shipped with Confluence but not included in Viewport (since it is custom HTML).

Missing resources

most themes are based off the webhelp theme. If you started from scratch, you want to include the Atlassian resources to render some macros and default components used by these macros.

CODE

$page.resources.css
$page.resources.js
$page.resources.meta

Missing metadata

Finding what is missing requires to see the error logged in the console of the developer tool panel. (CMD+ALT+I or F12)

Most of the code gets minified, which is why we have to expand it (Chrome dev tools comes with a handy button to beautify the code with the { } button

Then we look where, in this case, g is defined:

AJS.Meta.get("remote-user") concludes, that the script is looking for the meta data.

If we look at the source code of a Confluence page with a team calendar macro loaded, we can see what is in place for the meta data:

Now we can just add that code to the viewport theme. However, the script expects a user here, possibly to define which calendar items to show. So we need to fetch the username of the currently logged in user. You can look into our documentation about placeholders to find out how to fill in the gaps.

CODE

<meta name="ajs-remote-user" content="$user.username">

That's it - now the calendar items are loading.

Generally, you can use these meta data tags, and almost all macros will work:

CODE

<meta id="atlassian-token" name="atlassian-token" content="$xsrfToken.token">
<meta name="ajs-atl-token" content="$xsrfToken.token">
<meta name="ajs-confluence-flavour" content="VANILLA">

<meta name="ajs-page-id" content="$page.id">
<meta name="ajs-latest-page-id" content="$page.id">
<meta name="ajs-space-key" content="$repository.key">
<meta name="ajs-space-name" content="$repository.key">

<meta name="ajs-context-path" content="$contextPath">
<meta name="ajs-base-url" content="$viewport.absoluteLink">
<meta name="ajs-remote-user" content="$user.username">
<meta name="ajs-user-locale" content="en_GB">