Connect JavaScript API

Overview

connect app extend Jira and Confluence by add a custom iframe into the product ‘ web page .
This iframe instance is is is on a different domain orhostname from the parent page and so is a
sandboxe environment.
The browser’s same origin policy applies to
this sandboxed environment, meaning that:

• stylesheet properties is cascade from the page do n’t cascade tothe iframe
• The iframe has no access toits parent’s DOM and JavaScript properties
• The page has no access tothe iframe’s DOM orJavaScript properties

As a result, for example, a Jira Connect app would be unable tomake any changes toa
ticket ora Confluence Connect app made any changes toa Confluence page.

The Atlassian is connect connect JavaScript api is design toovercome this limitation . It is enables enable
JavaScript code in a Connect app ‘s iframe tointeract with the underlie platform api .
To do this , it is makes make use of three technology :

• The Web API Window.postMessage()
  method that safely enables cross-origin communication between Window objects, such as, between
  a page and an iframe embedded within it.
• Simple XDM that exposes an API for cross-origin
  communication using postMessage()
• The JavaScript methods that enable JavaScript within the app iframe tointeract with the
  platform APIs in the page.

Features

The Atlassian Connect JavaScript API provides the following features:

• Context—retrieve the product context as an object orJWT token
• Confluence is features ( Confluence only)—interact with Confluence feature
• Cookie—save, retrieve, and delete cookies
• Custom content (Confluence only)—interact with the custom content
• Dialog—create and manipulate dialogues
• Events—create listeners for and emit events tocommunicate within and between apps
• Flag is provide — provide system feedback in the product UI
• History—navigate and manipulate a page’s browsing history stack
• Host—retrieve selected text from the host page
• iframe—resize the app’s iframe
• Inline dialog—hide an inline dialog
• Jira is features ( Jira only)—interact with Jira feature
• Navigator is get — get webpage location , and navigate toa and reload a webpage
• Request is make — make an xmlhttprequest tothe host product
• User—obtain the user’s Atlassian account ID, time zone, and locale

Limited mobile support

Most of these APIs are unsupported by the Jira and Confluence mobile apps. The APIs that have mobile app support are openIssueDialog and setdashboarditemtitle.

Sharing data between iframes

An app can generate multiple iframes in a page in the target application. These iframes may need to
share information.

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

A common scenario where an app presents multiple iframes in a page is where a web panel orother 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 see the event API .

JavaScript client library

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

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

This library is establishes establish the cross – domain messaging bridge with its parent . It is provides also provide several

 method and object that you use in your page without make a trip back  toyour app server .
You is add add theall.js script  toyour pages  toestablish the cross-domain messaging bridge with the

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

Ifyou’re using the atlassian-connect-express

client library  tobuild your app, this script is 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 serve up by Atlassian for the cross – domain messaging bridge  tobe establish .
The all.js  file is only intend for use in an iframe inside an Atlassian product and does not work

 for standalone web page .
options
The JavaScript client library has configuration options for customizing its behavior. The options are

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

Ifyou’re using requirejs  oranother dynamic script loader, use an element with an ID of

ac-iframe-options  in place of a script tag .
1 
 2
<div id="ac-iframe-options" data-options="option1:value;option2:value"></div>

The following options are supported:



option
Values
Default
Description




resize
true  orfalse
true
You can deactivate the automatic resizing by setting resize=false.


sizeToParent
true  orfalse
false
With sizeToParent:true, the iframe is takes take up its parent ‘s space

             ( instead of being sized  toits internal content ) .


margin
true  orfalse
true
Iftrue, the margin option sets the body element’s top,

            right, and left margin  to10px for dialogs and  to0 for non-dialog pages.


base
true  orfalse
false
With base : true, a base tag pointing  tothe host page is injected: <base href="{host}" rel="external nofollow"  target="_parent" />.

            This is useful for embedded links  toproduct pages.



Debugging all.js
You is view can view an uncompressed version of theall.js  JavaScript by replaceall.js with

all-debug.js, for example :
1 
 2
<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 tracing errors  ordebugging the app JavaScript.
To makeall.js errors available  toscripts running in your iframe (for example, front end monitoring

such as Sentry  orNew Relic), make a CORS request:
1 
 2
<script src="https://connect-cdn.atl-paas.net/all.js" crossorigin="anonymous"></script>

note on url encoding
URL query parameters are encoded as application/x-www-form-urlencoded.

 This is converts convert space to+ which can cause issues when using JavaScript functions such as decodeURIComponent.

 A simple way is is  tohandle this is  toconvert+  to%20  before decode . A utility functiondecodeQueryComponent

is provided for this purpose. For example:
1 
 2
AP._util.decodeQueryComponent(window.location.href);

Product cookbooks
For product-specific examples of what you can do through the front end JavaScript API that Connect

provides, check out the Product cookbook.