Providing an image as a macro placeholder in the editor


Status:	LEGACY This tutorial applies to Confluence versions that have reached end of life.

Overview

As of Confluence 4.0 a plugin developer can specify an image to use as a macro placeholder in the editor, rather than the placeholder image itself. This is only applicable to macros without a body.

The image provided can come from anywhere within the current Confluence context, it can be a static image or dynamically generated by your plugin.

In order to make use of this feature you must edit your plugin and implement the EditorImagePlaceholder interface.

If you macro has a body and this is used for that macro, the user will have no way of modifying the body of the macro.

For a complete example of how to use an image placeholder and how to use the pluggable macro property panels, see the Confluence Status Macro, available on bitbucket: confluence-status-macro

Example

For this we will use a new cheese macro that renders a static image of cheese both in the editor and when it is executed.

1
2
package com.atlassian.confluence.plugin.cheese;

import ...

public class NewCheese implements Macro, EditorImagePlaceholder, ResourceAware
{
    private static final String IMAGE_PATH = "/download/resources/com.atlassian.confluence.plugin.cheese.cheese/cheese.jpg";

    private final SettingsManager settings;

    public NewCheese(SettingsManager settings)
    {
        this.settings = settings;
    }

    public ImagePlaceholder getImagePlaceholder(Map<String, String> params, ConversionContext ctx)
    {
        return new DefaultImagePlaceholder(IMAGE_PATH, new Dimensions(640, 480), false);
    }

    public String execute(Map<String, String> params, String body, ConversionContext ctx) throws MacroExecutionException
    {
        return "<img src=\"" + settings.getGlobalSettings().getBaseUrl() + "/" + getImageLocation(params, ctx) + "\">";
    }

    public BodyType getBodyType()
    {
        return BodyType.NONE;
    }

    public OutputType getOutputType()
    {
        return OutputType.BLOCK;
    }
}

For this example we are just referencing a resource we are providing in this plugin, the cheese.jpg file:

1
2
<resource type="download" name="cheese.jpg" location="img/cheese.jpg">
    <param name="content-type" value="image/jpeg"/>
</resource>

The String referenced in the ImagePlaceholder should be relative to the confluence base url, the editor will automatically make sure that this points to the correct url. Absolute URLs are not supported for this feature.

The image rendered in the editor as the placeholder will behave just like a regular bodyless marco placeholder, the property panel will still function correctly and the user will be able to edit it just like a macro. Any parameter changes in the macro browser will cause the image to be reloaded - so that changes can be seen.

The ImagePlaceholder interface is described below

1
2
public interface ImagePlaceholder
{
    /**
     * Returns the url to the image to render, relative to the Confluence base url.
     *
     * @return The url relative to the Confluence base url.
     */
    String getUrl();

    /**
     * Returns the dimensions that the image is to be rendered as. Returning null will
     * render the image at its default size.
     *
     * @return An instance of {@link Dimensions} representing the image dimensions.
     */
    Dimensions getDimensions();

    /**
     * Returns true if the image should have the macro placeholder chrome applied to it.
     *
     * @return True if placeholder chrome is to be applied.
     */
    boolean applyPlaceholderChrome();
}