atlassian-connect-js
v5.1.74Atlassian Connect JS
The javascript library which backs Atlassian Connect.
Based on Simple XDM
Hello API example
Modules allow you to expose new connect API's to add-on iframes.
connectHost.defineModule('example', {
sayHello: function(name){ alert('hello ' + name); }
});
An add-on may now call:
AP.example.sayHello('fred');
which will create an alert with "hello fred"
Hello event example
Events are used when a callback needs to be called multiple times.
var eventName = 'hello';
// addonFilter can be a filter function or object to match against add-ons (a blank object denotes sending to all add-ons).
var addonFilter = {
addon_key: 'my-addon',
key: 'my-module-key'
};
var eventData = {
name: 'fred'
};
connectHost.broadcastEvent(eventName, addonFilter, eventData);
An addon may listen with:
AP.register({
hello: function(name){ alert('hello ' + name); }
});
which will create an alert with "hello fred"
Listening to keystrokes example
Keyboard events are only sent to the currently focused frame. To allow a more seamless experience for users we allow a convenient way to listen for events inside an iframe.
var extension_id = 'addon_key__module_key__ab1j4';
var escapeKeyKeycode = 27;
var keymodifiers = [];
function callback(data) {
/** data = {
* extension_id: addon_key__module_key__ab1j4
* addon_key
* key
* keycode: 27
* modifiers: []
* }
*/
alert(data.keycode + ' key pressed inside add-on iframe');
}
// an iframe must load before you can bind to it.
connectHost.onIframeEstablished(function(extension){
connectHost.onKeyEvent(extension.extension_id, escapeKeyKeycode, callback);
});
Advanced Modules
Some times you need a more complex API than simple RPC -> callback. You can define a Class module which will create a proxy class in the add-on.
class Foo {
constructor(foo) {
this.foo = foo;
}
getFoo(cb) {
if (typeof cb === 'function') {
cb(this.foo);
}
}
};
host.defineModule('moduleWithClass', {
foo: {
constructor: Foo, // Class must be destructured in API spec
getFoo: Foo.prototype.getFoo
}
});
The addon can then use the proxy to call methods on an instance of your host class:
var bar = AP.moduleWithClass.foo('bar');
bar.getFoo(function (foo) {
console.log(foo);
});
Lifecycle
- connectHost.onIframeEstablished - a callback triggered when an iframe successfully contacts the parent page.
- connectHost.onIframeUnload - a callback triggered when window.onunload is called inside the iframe.
- connectHost.destroy - call this to clean up destroyed connect add-ons - helpful for SPA web apps that need to free memory.
JWT and the content resolver
There are instances when a connect add-on is created but the URL is unknown (or if you use JWT, that it's expired).
In these instances you can register a function to delegate to. Connect will call this function and wait before creating the iframe until it has responded - usually requiring your application to callback to your server. The example below uses jQuery promises, but any promise library should work (note: jQuery.ajax also returns a promise).
function contentResolver(extension) {
var promise = jQuery.Deferred(function(defer){
// do some work here, then resolve to what would be passed to connectHost.create
defer.resolve({
url: 'the full iframe url from the server',
addon_key: 'my-addon-key',
key: 'my-module-key',
options: {} // same options as connectHost.create({options:{}})
});
}).promise();
return promise;
}
connectHost.registerContentResolver.resolveByExtension(contentResolver);
Analytics
You can expose an analytics event reciever as follows:
define('ac/analytics', () => {
return {
emitGasV3: (eventType, eventData) => {
console.log('this is an alaytics event', eventType, eventData);
}
};
});
Requirements
- Node LTS (refer to
.nvmrc
) - NPM
Installation
NPM install takes care of everything for you.
npm install
Building
To build the distribution:
npm run build
Running tests
We use Karma for running our Jasmine tests.
To run tests in watch mode:
npm run karma
Running tests with saucelabs
Tests are automatically run in Sauce Labs from Bitbucket Pipelines. They run using all supported browsers. You can run these yourself as follows:
Set your Sauce Labs credentials using the SAUCE_USERNAME and SAUCE_ACCESS_KEY environment variables.
Then run the tests using:
SAUCE_LABS=true npm test
Alternatively you can enter Sauce Labs credentials at run time with:
SAUCE_LABS=true SAUCE_USERNAME=XXXXX SAUCE_ACCESS_KEY=XXXXX npm test
Linting && Coding Style Checks
ACJS follows the Atlassian Front-End Code Quality guidelines.
npm run lint
Point IntelliJ / Sublime / your editor of choice at the .eslintrc for linting as you edit.
Code Coverage
We use Istanbul for code coverage statistics.
To run tests and generate coverage results:
COVERAGE=true npm run karma-ci
Then point your browser at:
file:///<path to atlassian-connect-js>/coverage/index.html
Commands
To see a wider range of gulp commands run:
gulp --tasks
Dev loop
To automatically re-create the dist directory on code change, run:
gulp watch
To have your changes automatically loaded onto a locally running JIRA or Confluence instance, first make sure that you
include -Dconnect-js-v5=true
in your command to start the product. Then you can deploy the contents of your dist directory:
gulp deploy
By default, this will deploy to the v5 resources directory inside your local atlassian-connect
project, i.e.
/<path/to/my/projects>/atlassian-connect/jsapi-v5/src/main/resources/v5
. Changes will be automatically picked up by the
running product.
Contributing
Contributions are welcome! However, the versions and branches of this project are in a state of flux. Before starting work, please contact the Atlassian Connect team to ensure you understand the process you'll need to follow.
- Create an issue in the Atlassian Connect JavaScript API project.
- Create your feature branch off
master
.- Include your issue key and a short description.
- Push your changes.
- Create a pull request against this repository.
- If your changes will affect the functionality of the Connect plugin, create a feature branch in the product and make sure the build is green against your ACJS branch by updating the version consumed by the product.
Releasing a new version
This is now done via BitBucket Pipelines on the master branch.
The onecloud-build-bot
account executes this step as via the OAuth method described by these Bitbucket instructions
If you're an Atlassian developer and you wish to release a new version of Atlassian Connect JS for Atlassian products to use, follow this HOWTO.
Compatibility
Atlassian Connect supports the following browsers:
- Chrome latest stable
- Firefox latest stable
- Safari latest stable (on OS X only)
Metadata
- Apache-2.0
- Whatever
- Unknown
- released 11/12/2018