Extension Factories
Extension API
Extension Points

Page

A page extension allows the creation of custom web page and rendering a navigation link in the product UI.

Supported attributes

NameTypeDescription
This extension doesn't support any attributes

Supported annotations

NameTypeDescription
@clientside-extension *-Indicates that the next function is an extension factory to be consumed by the webpack plugin.
@extension-point *stringDefines the location where the page navigation link will be rendered.
@label *stringDefines a label that's going to be used when rendering navigation link. The value can be either a raw string or a property key than will be translated.
@page-url *string

Defines an url of the web page. The page will be accessible at this url prefixed with /plugins/servlet/<<page-url>>

Example: Using @page-url /labels will register the page at /plugins/servlet/labels URL.

@page-title *stringDefines a title of the web page. The value can be either a raw string or a property key than will be translated.
@page-decoratorstring

A custom page decorator. The default value is atl.general. To read more about page decorators refer to the documentation.

List of built-in decorators supported by all products:

  • atl.admin
  • atl.general
  • atl.popup
  • atl.userprofile
@page-data-providerstring

A page data provider Java class. Page data providers can be used to provide a custom set of a server-side data into your browser page extension.

To read more about the page data providers check the usage section.

Example: @page-data-provider com.example.plugin.MyDataProvider

@linkstring

Defines a custom URL that's going to be used when rendering navigation link. By default, the link value is not required.

Setting a custom link will overwrite the one generated from the @page-url annotation value.

@weightnumber

Determines the order in which the navigation link appears respect to others in the same location.

Extensions are displayed top to bottom or left to right in order of ascending weight.

@conditionstring | Condition, UrlReadingCondition

Defines one or multiple conditions that must be satisfied for the navigation link to be displayed.

The conditions are evaluated on the server, and created with Java.

If one of the conditions is not met, the code of the extension won't be loaded in the client.

For more information about the conditions please refer to the examples of Web items documentation.

* required

Usage

Basic page

1
2
import { PageExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @label "My page"
 * @page-url /my-page
 * @page-title "My page"
 */
export default PageExtension.factory((container) => {
    // attach content to the container

    container.innerHTML = 'My new page!';
});

Using translations

The @label and @page-title annotations support passing either a raw string value or a property key that will be used to render translated value.

For more information about the translation mechanism and the *.properties files, refer to the documentation.

my-translations.properties

1
2
some.property.key.button.title = A custom page
some.property.key.page.title = My custom page

my-extension.ts

1
2
/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @label some.property.key.button.title
 * @page-title some.property.key.page.title
 * @page-url /my-custom-page
 */
export default PageExtension.factory((container) => {
    container.innerHTML = '<div>My custom page</div>';
});

Using a custom page decorator

The @page-decorator annotation allows you to configure the base markup of the page. By default, the page will be rendered using the atl.general decorator that is a standard blank page with basic navigation.

If your page needs to be rendered with the admin layout, you can use atl.admin decorator. Different products can provide an additional custom page decorators you can use.

To read more about page decorators, refer to the documentation.

1
2
/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @label "My admin page"
 * @page-url /my-admin-page
 * @page-title "My admin page"
 * @page-decorator atl.admin
 */
export default PageExtension.factory((container) => {
    container.innerHTML = '<div>Very secure page!</div>';
});

Using data provider

If you need to retrieve a server-side data in your page extension, you can use the @page-data-provider annotation to specify a Java data provider class.

The extension data provider class needs to implement ExtensionDataProvider interface and return Jsonable data.

For information about returning the more complex large JSON structures refer to the documentation for data providers.

MyDataProvider.java

1
2
package com.example.plugin;

import com.atlassian.json.marshal.Jsonable;
import com.atlassian.json.marshal.wrapped.JsonableString;
import com.atlassian.plugin.clientsideextensions.ExtensionDataProvider;

/**
 * A simple DataProvider class that returns a string as JSON
 */
public class MyDataProvider implements ExtensionDataProvider {
    @Override
    public Jsonable get() {
        return new JsonableString("Hello world!");
    }
}

my-extension.ts

1
2
type DataPayload = 'string';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @label "My page"
 * @page-url /my-page
 * @page-title "My page"
 * @page-data-provider com.example.plugin.MyDataProvider
 */
export default PageExtension.factory<DataPayload>((container, data) => {
    container.innerHTML = `<p>${data}</p>`; // Outputs <p>Hello World!</p>
});

Rate this page: