Extending the Image Properties Dialog
This tutorial applies to Confluence 5.1.
Level of experience:
Intermediate. Our tutorials are classified as 'beginner', 'intermediate' and 'advanced'. This one is at 'intermediate' level, so you will need to have developed a few plugins before to follow it.
It will take you approximately 1 hour to complete this tutorial.
The source code of the plugin used in this tutorial is hosted on Bitbucket: confluence-image-hover-effects-demo-plugin.
On this page:
The Image Properties dialog in Confluence 5.1 and later is launched from the property panel displayed when a particular image is selected in the Confluence editor. Additional panels can be added to this dialog to affect the current image in different custom ways.
This plugin inserts a new tab called "Hover Effects" in the Image Properties dialog. Clicking on this tab launches the demo panel, which contains several hover effect options that can be applied to the current image. From this starting point, it is possible to create more advanced customisations for the Image Properties dialog.
Screenshot: The demo 'Hover Effects' panel
In order to do this, you will create a Confluence plugin, which will consist of the following components:
- A Google Closure "Soy" template for rendering the panel's HTML markup.
- A CSS file that applies the hover effects.
- An internationalisation (i18n) properties file, to provide default English text for the panel
- A plugin XML descriptor file which registers all the plugin modules with Confluence.
The extension point used by this plugin is only available in Confluence 5.1 and later.
Step 1. Create the Plugin Project
The Atlassian Plugin SDK provides a number of
-plugin commands you can use to generate stub code for your plugin.
- Run the atlas-create-confluence-plugincommand and enter the following information when prompted:
- Open the
pom.xmlfile that was generated by the previous step, and update the information in this file to match your organisation and project name.
src/main/javaand any other Java code in the generated project. This plugin will not contain any Java code.
Step 2. Create a Soy template for the custom panel
- In the
src/main/resources/directory, create a new directory for your plugin resources called
Create a new Soy template -
src/main/resources/templates/hover-effects-panel.soy, with the following content:
The template should contain the markup you want to appear in the panel you're going to add to the Image Properties dialog. In this case, we display a form field with a label that has an i18n key of 'image.hover.effects.fade.label' and some radio button options. You can also see that this template accepts a parameter 'fadeSelection', which is used to determine which radio button should be selected by default.
src/main/resources/js/hover-effects-panel.js, with the following content:
AJS.toInit wraps the function containing all of the logic to initialise our panel. The function is passed a reference to jQuery and executed when the DOM is ready.
We have to wait until the Image Properties dialog has been created before we can add our panel. This is done by binding to the
dialog-created.image-properties event and then calling
Confluence.Editor.ImageProps.registerPanel from our event handler.
Confluence.Editor.ImageProps.registerPanel accepts the following parameters:
linkId:This identifies the tab to associate your panel with, it must match the linkId that you specify when adding the web item in Step 6.
panelContent:This should be a jQuery object containing the contents of your panel. On line 10 we call the template defined in Step 2 and create a jQuery object from the generated markup.
panelClass:This class will be added to the panel's HTML element.
In this implementation we add a class to the image if one of the hover effect radio buttons has been selected. While initialising the panel, we also check whether the selected image has a class to indicate a specific hover effect - and if so, that effect is passed as a parameter to the Soy template so that the correct radio button is selected by default.
Step 4. Create CSS and i18n files to provide styling and text for the panel
src/main/resources/css/hover-effects.csscontaining the following CSS rules to apply the hover effects:
src/main/resources/i18n.propertieswith the following content to supply all the text shown on the panel:
Step 5. Register the plugin modules in the XML plugin descriptor
In the plugin XML descriptor file,
The important parts of the plugin descriptor are as follows:
- The web-item creates a new tab in the Image Properties dialog, which allows the new panel to appear. The
linkIdattribute on the link (in this case "image-hover-effects") must match the linkId parameter passed to
Confluence.Editor.ImageProps.registerPanelin Step 3.
- The web-resource that includes the Soy template must have the Soy transformer to work properly.
- Both web-resources define a
contextthat determines whether or not the resource is loaded on a particular Confluence page.
- The i18n resource declaration references the path to the i18n file without a "properties" suffix.
Step 6. Install into Confluence
You can start an instance of Confluence with
atlas-run, or build the plugin with
atlas-package and install it into your existing Confluence instance.
The result when opening the Image Properties dialog via the editor in Confluence should look like the screenshot below.
Screenshot: The demo 'Hover Effects' panel
If the new item does not appear on the left-side of the Image Properties dialog, ensure you have the web-item correctly registered in
atlassian-plugin.xml. Ensure you have installed the plugin in Confluence and that the plugin is enabled.
Because your JS code is loaded the "editor" context, it will be included with the "batch.js" file which includes "editor" in the URL.