JavaScript API

Sandboxing

An iframe instance whose parent and child reside on different domains or hostnames constitutes a sandboxed environment. The contained page has no access to its parent. These restrictions are imposed by the browser's same origin policy.

There are a few limitations applicable to iframes:

  • Stylesheet properties from the parent do not cascade to the child page
  • Child pages have no access to its parent's DOM and JavaScript properties
  • Likewise, the parent has no access to its child's DOM or JavaScript properties

However, Atlassian Connect makes use of a technique called cross-domain messaging. This technique uses postMessage to pass data between the iframe and its parent.

Atlassian Connect transparently enables cross-domain messaging in its page modules. One benefit you'll see from this is that your app's page modules are automatically resized based on its content when loaded on the page.

Only content within an element with the class ac-content will be resized automatically. Content without this identifier is sized according to the body element, and is not dynamically resized. The recommended DOM layout for your app is:

1
2
3
4
5
6
7
8
<div class="ac-content">
    <p>Hello World</p>
    <div id="your-id-here">
        <p>Addon content goes here</p>
    </div>

    ...this area reserved for our resize sensor divs
</div>

Sharing data between iframes

A single app can generate multiple iframes in a particular page in the target application. Depending on the use case for the app, the iframes may need to share information between each other.

The Atlassian Connect JavaScript client library, all.js, provides a publish/subscribe mechanism that you can use to exchange data between iframes.

A common scenario in which a single app presents multiple iframes in a page is where a web panel or other page element spawns a dialog box.

The only restriction on the data shared in this manner is that it must be serializable using the structured clone algorithm.

For more information on the event API visit the events documentation.

JavaScript client library

Atlassian Connect provides a JavaScript client library called all.js.

1
https://connect-cdn.atl-paas.net/all.js

This library establishes the cross-domain messaging bridge with its parent. It also provides several methods and objects that you can use in your pages without making a trip back to your app server.

You must add the all.js script to your pages in order to establish the cross-domain messaging bridge. Make sure your pages include the following script:

1
<script src="https://connect-cdn.atl-paas.net/all.js"></script>

If you're using the atlassian-connect-express client library to build your app, this will automatically be inserted into your pages at run time.

Note:

Don't download the all.js file and serve it up from your app server directly. The all.js file must be served up by Atlassian in order for the cross-domain messaging bridge to be established.

Options

The JavaScript client library has some configuration options for customizing its behavior. The options are passed using the data-options attribute.

1
<script src="https://connect-cdn.atl-paas.net/all.js" data-options="option1:value;option2:value"></script>

If you are using requirejs or other dynamic script loader, use an element with an id of ac-iframe-options in place of a script tag.

1
<div id="ac-iframe-options" data-options="option1:value;option2:value"></div>

The following options are currently supported:

OptionValuesDefaultDescription
resizetrue or falsetrueYou can deactivate the automatic resizing by setting resize=false.
sizeToParenttrue or falsefalse`With sizeToParent:true, the iframe will take up its parent's space (instead of being sized to its internal content).
margintrue or false`trueIf true, the margin option sets the body element's top, right and left margin to 10px for dialogs, and to 0 for non-dialog pages.
basetrue or falsefalseWith base:true, a base tag pointing to the host page is injected: . This can be useful for embedded links to product pages.

Debugging all.js

A non-compressed version of the all.js javascript can be viewed by replacing all.js with all-debug.js for example:

1
2
3
<script src="https://connect-cdn.atl-paas.net/all.js"></script>
<!-- replace with -->
<script src="https://connect-cdn.atl-paas.net/all-debug.js"></script>

This can be helpful when trying to trace errors or debug the app javascript.

Note on URL Encoding

URL query parameters are encoded as application/x-www-form-urlencoded. This converts spaces to + which can cause issues when using JavaScript functions such as decodeURIComponent. A simple way to handle this is to convert + to %20 before decoding. A utility function decodeQueryComponent is provided for this purpose. For example:

1
2
3
AP.require("_util", function(util){
  alert(util.decodeQueryComponent(window.location.href));
});

Cookbook

The cookbook is filled with snippets of client side JavaScript code, providing examples for making simple client side apps, and gathering data from the products JavaScript API methods.

Product cookbooks

For product-specific examples of what you can do through the front end JavaScript API that Connect provides, check out the Connect cookbook.