Web Item Provider plugin module

Purpose of this Module Type

Web Item Provider plugin modules allow plugins to define web-items dynamically in application menus.

Configuration

The root element for the Web Item Provider plugin module is web-item-provider. It allows the following attributes and child elements for configuration:

Attributes

Name*

Description

class

The class which implements this plugin module. You need to write your own implementing class and include it in your plugin. See the plugin framework guide to [creating plugin module instances](/server/framework/atlassian-sdk/creating-plugin-module-instances/).

state

 

Indicate whether the plugin module should be disabled by default (value='disabled') or enabled by default (value='enabled').

Default: enabled.

i18n-name-key

The localisation key for the human-readable name of the plugin module.

key

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.

 

1
2
<web-item-provider
key="appProps"
class="com.example.MyWebItemProvider"/>

 

In the example, appProps is the key for this particular module declaration, for web-item-provider, in this case.

name

The human-readable name of the plugin module. 

Used only in the plugin's administrative user interface.

section

Location into which the web items should be placed.

For non-sectioned locations, this is just the location key.

For sectioned locations it is the location key, followed by a slash ('/'),

 and the name of the web section in which it should appear.

system

Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins.

Default: false.

*the class and section attributes are required.

Elements

This table summarises the elements. The sections below contain further information.

Name

Description

description

The description of the plugin module. The 'key' attribute can be specified to declare a localisation key for the value instead of text in the element body. 

I.e. the description of the web item provider.

param

Parameters for the plugin module. Use the 'key' attribute to declare the parameter key, then specify the value in either the 'value' attribute or the element body. This element may be repeated. An example is the configuration link described in [Adding a Configuration UI for your Plugin](/server/framework/atlassian-sdk/adding-a-configuration-ui-for-your-plugin/).

This is handy if you want to use additional custom values from the UI.

Param Elements

Param elements represent a map of key/value pairs, where each entry corresponds to the param elements attribute: name and value respectively. If the value attribute is not specified, the value will be set to the body of the element. I.e. the following two param elements are equivalent:

1
2
<param name="isPopupLink" value="true" />
<param name="isPopupLink">true</param>

These can be accessed from the module descriptor of the web-item provider, e.g.

1
2
webItemProviderModuleDescriptor.getParams().get("isPopupLink"); // returns true

Example

Providing web items for the admin section

Here is an example atlassian-plugin.xml file containing a single web item provider:

1
2
<atlassian-plugin name="Hello World Plugin" key="example.plugin.helloworld" plugins-version="2">
    <plugin-info>
        <description>A basic web item module test</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.0</version>
    </plugin-info>

    <web-item-provider key="google_home" name="Google Home" section="system.admin/example1"
                       class="com.example.MyWebItemProvder">
        <description key="item.google.home.desc">Simple link to google.com.</description>
        <param name="isPopupLink">true</param>
    </web-item-provider>
</atlassian-plugin>

with a starter implementation of the WebItemProvider interface:

1
2
package com.example;

import com.atlassian.plugin.web.api.WebItem;
import com.atlassian.plugin.web.api.descriptors.WebItemProviderModuleDescriptor;
import com.atlassian.plugin.web.api.provider.WebItemProvider;

import javax.annotation.Nonnull;
import java.util.Map;

import static java.util.Collections.singleton;

public class MyWebItemProvider implements WebItemProvider {
    private boolean isPopupLink;
    private String section;

    @Override
    public void init(@Nonnull final WebItemProviderModuleDescriptor<WebItemProvider> moduleDescriptor) {
        this.isPopupLink = moduleDescriptor.getParams().get("isPopupLink");
        this.section = moduleDescriptor.getSection();
    }

    @Override
    public Iterable<WebItem> getItems(Map<String, Object> context) {
        return singleton(new WebItem() {
            @Nonnull
            @Override
            public String getSection() {
                return section;
            }

            @Nonnull
            @Override
            public String getUrl() {
                return isPopupLink ? "#popup" : "google-home";
            }
            
            // rest of implementation
        });
    }
}

Plugin Modules Web Item Plugin Module

Rate this page: