Path Converter Module


Confluence 2.8 and later

Path Converter plugin modules are useful for developers who are writing Confluence plugins. The Path Converter modules allow you to install custom path mapping as a part of your plugin.

The Path Converter Plugin Module

Each path converter can be used to map a friendly URL to an action either within Confluence or provided by your plugin. Here is an example atlassian-plugin.xml file containing a single path converter:

<atlassian-plugin name="Hello World Converter" key="confluence.extra.simpleconverter">
<description>Example Path Converter</description>
<vendor name="Atlassian Software Systems" url=""/>

<path-converter weight="10" key="example-converter" class="plugin.ExamplePathConverter"/>


  • The class attribute specifies a class that implements com.atlassian.confluence.servlet.simpledisplay.PathConverter.
  • The weight element defines when the path converter is executed in relation to the other converters. See DOC:Notes below.
  • The key is the normal plugin module identifier.


This converter is used by Confluence to convert the friendly /display/SpaceKey/PageTitle/ URL format into a request against the correct WebWork action.

public class PagePathConverter implements PathConverter
    private static final String DISPLAY_PAGE_PATH = "/pages/viewpage.action?spaceKey=${spaceKey}&title=${title}";

    public boolean handles(String simplePath)
        return new StringTokenizer(simplePath, "/").countTokens() == 2;

    public ConvertedPath getPath(String simplePath)
        StringTokenizer st = new StringTokenizer(simplePath, "/");
        String spaceKey = st.nextToken();
        String pageTitle = st.nextToken();

        ConvertedPath path = new ConvertedPath(DISPLAY_PAGE_PATH);
        return path;

The handles method is called (in order of weight) on each converter and the first to return true will have its getPath method called.
The getPath method will convert the friendly path into a ConvertedPath object.

The ConvertedPath object expects a URL template and a series of parameters. It uses Velocity internally to merge the template and the parameters, producing a final URL.


The com.atlassian.confluence.servlet.simpledisplay.SimpleDisplayServlet will pass each incoming request that starts with '/display' to each of its configured converters. The converters will be checked starting with the converter with the lowest weight.

The PathConverters are autowired at registration time, so add a setter method on your converter to get access to Confluence's components.

public class MyPathConverter implements PathConverter
    private PageManager pageManager;

    // other methods    

    public void setPageManager(PageManager pageManager) 
        this.pageManager = pageManager;

Core Converters

Confluence includes a series of core path converters that are used to provide friendly URLs for standard Confluence resources.


Core PathConverter











You can use any weight for your converter. If the same weight is used by multiple converters, they are executed in order of registration.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport