Last updated Feb 21, 2024

Writing Confluence plugins

Confluence plugins (also known as apps or add-ons) provide a standard mechanism for extending Confluence. By adding plugins to Confluence you will be able to customise the site's look and feel, add new macros, event listeners and periodic tasks, and even introduce whole new features.

You can read the Confluence Plugin Guide for an overview of what plugins are. This document introduces Confluence plugins to developers who may want to write their own.

Ready to develop your first app? Our Plugin SDK is a great place to start.

Anatomy of a Plugin

A plugin is a single jar file that can be uploaded into Confluence. It consists of

  • A plugin descriptor
  • (Optional) Java classes
  • (Optional) Resources

Plugins are composed of a series of modules, each of which defines a point at which the plugin interfaces with Confluence.

Creating your Plugin Descriptor

The plugin descriptor is a single XML file named atlassian-plugin.xml that tells the application all about the plugin and the modules contained within it. See Creating your Plugin Descriptor.

Creating a Basic Macro Plugin Skeleton

While even the most basic plugin involves quite a few directories and config files, creating a plugin skeleton is pretty easy and straightforward. We have prepared a Maven 2 template which does almost all the work for you. Please refer to the documentation in the Atlassian Developer Network for instructions on setting up your development environment and creating the most basic Confluence macro plugin. You can use its basic code skeleton to evolve your plugin into one of the categories described below.

Confluence Plugin Module Types

There are plenty of plugin types in Confluence. If you are new to plugin development in Confluence, we strongly suggest you start by writing a simple Macro Plugin. Macros are easy to write and give you visual feedback at once. Since the default plugin created by the Maven 2 template is a macro too, you can get started in almost no time at all.

Once you know your way around the Confluence API, you can evolve your plugin into something else, or of course create a new plugin and start from scratch. Each of the following plugin type descriptions assumes you have been able to create the basic plugin skeleton mentioned in the above paragraph.

See Confluence Plugin Module Types.

Java Classes and Accessing Confluence Components

When you upload a plugin JAR file into Confluence, all the Java classes contained within the JAR are available for your plugin to access. You can include as many classes as you like, and have them interact with each other. Because Confluence and plugins can export components for your plugin to use, it's important that you follow the Java package naming conventions to ensure your plugin's classes do not conflict with Confluence classes or with other plugins.

If you are writing a Java implementation of a plugin module, you will be interested in Accessing Confluence Components from Plugin Modules.

Adding Plugin and Module Resources

A 'resource' is a non-Java file that a plugin may need in order to operate. See Adding Plugin and Module Resources.

The simplest kind of resource, supported with all plugin module types, is of type download, which makes a resource available for download from the Confluence server at a particular URL. See Adding Plugin and Module Resources.

Adding a Configuration UI for your Plugin

A plugin for an Atlassian application can specify internal links within the application, to allow the user to configure options for the plugin. This is useful where your plugin requires configuration or user-specific settings to work. See Adding a Configuration UI for your Plugin.

Ensuring Standard Page Decoration

If you're writing a plugin that is intended for more than one Atlassian application, you can use the standard page decorators supported by Confluence. This allows your plugin to generate new web pages with consistent decoration by the host application across the Atlassian products. See Using Standard Page Decorators.

Tutorials on Developing Confluence Plugins

If you would like a walkthrough on how to develop specific Confluence plugins, please check out our useful tutorials here: Tutorials

Rate this page: