Extending the Highlight Actions Panel
This tutorial applies to Confluence 5.4.
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-highlight-actions-demo-plugin
The highlight actions panel in Confluence is the panel that appears when text is selected. It contains buttons with additional actions the user can perform. By default, the user can:
- Quote the selected text in a comment.
- Create an issue in JIRA, and populate the Summary field with the selected text, if Confluence is linked to a compatible JIRA instance.
Screenshot: the highlight actions panel appears when text is selected
The highlight actions panel in Confluence is provided by the confluence-highlight-actions plugin.
In this tutorial you will extend the highlight actions panel to add a button that shows the number of times the highlighted text appears on the page.
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 highlight dialog
- In the
src/main/resources/directory, create a new directory for your plugin resources called
- Create a new Soy template -
src/main/resources/templates/highlight-demo-dialog.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 Highlight dialog. In this case, we display a heading with text that has an i18n key of 'highlightdemo.dialog.header.text' followed by the highlighted text and the number of occurrences.
src/main/resources/js/highlight-actions-demo-dialog.js, with the following content:
Confluence.HighlightDemoDialogs does two things:
- As Confluence could be using either the General (default) theme or the Documentation theme (in Confluence 5.10 or earlier), each theme needs a different positioning mechanism, the
_appendDialogTargetfunction will use
Confluence.DocThemeUtils.appendAbsolutePositionedElementto calculate the correct position of the selected text.
- Render the dialog content with
selectionObject. Show and hide handlers are also provided to handle these events.
src/main/resources/js/panel-helper.js, with the following content:
AJS.toInit wraps the function containing all of the logic to register our button.
registerButtonHandler function that lets us to register our own button to Highlight Actions panel. To successfully register the button, there are 2 parameters must be provided:
PLUGIN_KEY: plugin_key is the combination of the plugin key and button web item's key.
options: contains the group of event handlers needed for the button, and the important property
shouldDisplayto configure the context in which the button should displayed when text is selected, there are 3 supported contexts:
MAINCONTENT_ONLY: in page main content section.
COMMENT_ONLY: in comment section.
MAINCONTENT_AND_COMMENT: in both page main content and comment sections.
PLUGIN_KEY must follow the pattern described exactly, otherwise the button will not be shown.
Step 5. Create i18n file to provide text for the button and dialog header
src/main/resources/i18n.properties with the following content to supply all the text shown on the panel:
Step 6. Register the plugin modules in the XML plugin descriptor
In the plugin XML descriptor file,
The important parts of the plugin descriptor are:
- The web-item creates a new button in the Highlight Actions panel, which appears when user highlights text. For this simple tutorial, we used
styleClass, but this is not limited to AUI icons.
- 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 7. 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 the highlight actions panel is triggered should look like the screenshot below.
Screenshot: the highlight actions panel with new registers button
Screenshot: the highlight actions dialog
If the new button does not appear in the highlight actions panel, 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.