- Created by Robert Reiner, last modified on 11. Aug 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 8 Next »
Boost team fun and productivity on Confluence by small changes to the UI with short JavaScript userscripts
Browsers render Confluence pages in HTML when users traverse a Confluence site. The appearance of the page can be altered or additional functions can be applied to these pages by JavaScript code. Confluence users may use bookmarklets or userscripts to execute their own code from within their browser on these pages.
Teams in corporations may need to share these scripts and administration teams may need to prohibit code from uncontrolled sources to be executed in a corporate environment. This is when Userscripts for Confluence enters the stage. Userscripts for Confluence is an app for Confluence Server that allows to administrate JavaScript code to be executed in the browser of Confluence users.
While bookmarklets need to be executed by users explicitly by clicking on links in the browser's bookmarks, userscripts are executed when predefined conditions are meet, typically by the use of a browser add-on.
Userscripts for Confluence allows to execute scripts stored on the server side. The administration team defines the parameters that activates a particular userscript. A userscript can be executed on a given page
- if a user is member of a certain Confluence group
- if a user's name is explicitly registered
- if the current page
- is part of a certain space
- is part of a space labelled with a certain category
- is labelled with a given label
Or a combination of user and page information. Like
- a page with a given label for users of a given group
- a space identified by a key for a user with a specific name
By providing scripts to be executed in explicitly specified contexts, users of Confluence can implement a number of use cases.
- Hide elements like
- macros from the macro browser
- space blueprints from the space wizard
- page blueprints from the page wizard
- Add page elements
- links or buttons
- divs and paragraphs
Please note that all scripts are executed on the client side, within the browser of the user visiting the page.
Userscripts
A userscript is JavaScript code that is executed on a page. These scripts are usually configured by users to add additional functions on web pages they are visiting. A browser add-on allows them to add userscripts and define on which pages they should run.
Userscripts for Confluence is a bit different. The userscript is configured for users by the administration team. Hence users can benefit from additional functions without bothering to validate the fitness of a script for their task by themselves. This makes using Confluence easier especially for team members without programming skills. It also allows to easily share scripts that boost the productivity for teams.
A userscript consists of
- an identifier consisting of
namespace,name, andversion - a reference to the JavaScript code (
script) - metadata, like a a
description, and a reference to further information (documentation), andauthor - an activation record (
activation) that defines when the userscript is actually executed
Here is the basic structure of a userscript in JSON.
{
"namespace": "...",
"name": "...",
"version": "...",
"script": "...",
"description": "...",
"documentation": "...",
"author": "...",
"activation": {
...
}
}
Administration of Userscripts
The userscripts resource provides operations to add, remove, and alter userscripts. The userscript code is typically stored on a remote server (like an internal Git repository) or on a Confluence page as attachment. The userscript resource manages metadata and a reference to the userscript code.
| Name | Short Description | Path / Method |
|---|---|---|
| Create Userscript by JSON | Creates a new userscript. | |
| Delete Userscript | Deletes a userscript uniquely identified by its namespace, name, and version. | |
| Get all Userscripts | Provides access to the list of userscripts that are currently stored in the userscripts repository. | |
| Get Userscript | Provides access to a unique userscript by its namespace, name, and version. | |
| Update Userscript by JSON | Updates an existing userscript. |
Activation Record
The activation record is part of a userscript.
{
...
"activation": {
"preserve": false,
"space": ["...", ...],
"category": ["...", ...],
"label": ["...", ...],
"group": ["...", ...],
"user": ["...", ...]
}
}
- No labels
