- Created by Robert Reiner, last modified on 16. Oct 2020
A short introduction to write userscripts for the Userscripts for Confluence App.
- Audience
- Type
- Level of Experience
A Userscript is executed in the Confluence environment. Therefore the usual JavaScript infrastructure, like access to libraries and context information via AJS, is available.
This is a short introduction to show you the very basics of writing JavaScript code for Confluence. It also shows to examples to get you started.
Basics
To ensure that the AJS infrastructure is fully initialized when the userscript is executed, wrap your code inside this:
"use strict";
AJS.toInit(function () {
// your code starts here ...
}
The use of the strict mode is recommended, but not strictly necessary.
The AJS object allows to access context information via AJS.params. For instance AJS.params.remoteUser provides access to the currently logged in user.
Since AJS wraps the libraries provided by Confluence, including jQuery, elements of a page can be accessed via AJS.$('#my-selector') (see Selecting Elements on the jQuery's website).
Examples
Here are two examples that shows how easy it is to create JavaScript code to alter the user interface.
Hide an Element on a Web Page
This a very short userscript to hide the browse-menu-link for anonymous users, as shown in the example on How to use JavaScript in Confluence by Atlassian. would look like this:
"use strict";
AJS.toInit(function () {
if (AJS.params.remoteUser == '') {
AJS.$('#browse-menu-link').hide();
}
}
This code would hide the referenced element for anonymous users.
Hide projectdoc Tools
The following example shows how to hide tools provided by the projectdoc Toolbox. While this is nonsense for users of the projectdoc Toolbox, it may be a valuable tool to hide the elements on spaces where teams actually do not use the projectdoc Toolbox.
"use strict";
AJS.toInit(function () {
const bodyNodes = document.getElementsByTagName('body');
if (bodyNodes.length > 0) {
const targetNode = bodyNodes[0];
const config = {attributes: true, childList: true, subtree: true};
const callback = function (_mutationsList, _observer) {
if (AJS) {
AJS.toInit(function () {
function hideElements($element) {
if ($element) {
$element.css("display", "none");
}
}
function hideSpaceBlueprints() {
const $templateElements =
AJS.$('#create-dialog .templates .template[data-blueprint-module-complete-key*="projectdoc"][data-create-result="space"]');
hideElements($templateElements);
}
function hidePageBlueprints() {
const $templateElements =
AJS.$('#create-dialog .templates .template[data-blueprint-module-complete-key*="projectdoc"]:not([data-create-result="space"])');
hideElements($templateElements);
}
function hideMacros() {
const $macroElements = AJS.$('#select-macro-page .dialog-page-body .macro-list-item[id*="projectdoc"]');
hideElements($macroElements);
}
function hideAutocompleteMacros() {
const $macroElements = AJS.$('li>a[class*="autocomplete-macro-projectdoc"]');
if ($macroElements) {
$macroElements.parent().css("display", "none");
}
}
hideSpaceBlueprints();
hidePageBlueprints();
hideMacros();
hideAutocompleteMacros();
});
} else {
console.log("WARN: AJS not found in context, therefore no adjustment due to modifications.");
}
};
const observer = new MutationObserver(callback);
observer.observe(targetNode, config);
} else {
console.log("WARN: No body element found, modifications on this document are not tracked.");
}
});
This may be used as a template to adjust the options for a specific context where users want to focus on a special subset of tools.
The current version of the JavaScript file is available via hide-projectoc-tools.js on Bitbucket.
Resources
- How to use JavaScript in Confluence
- Provides basic information on how to use JavaScript on Confluence. Userscripts provide an alternative way to integrate JavaScript code, but the design rules for writing JavaScript code for Confluence still apply.
- Atlassian User Interface
- AUI is a tailor-made frontend library for creating a user interface according to the Atlassian Design Guidelines.
- JQuery Learning Center
- Information on how to use jQuery on the jQuery website.
- JavaScript
- Information on JavaScript on the MDN web docs website.
- MutationObserver
- The
MutationObserverinterface provides the ability to watch for changes being made to the DOM tree.
