Web Section Provider plugin module

Purpose of this Module Type

Web Section Provider plugin modules allow plugins to define web-sections dynamically in application menus.

Configuration

The root element for the Web Section Provider plugin module is web-section-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-section-provider
key="appProps"
class="com.example.MyWebSectionProvider"/>

 

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

name

The human-readable name of the plugin module. 

Used only in the plugin's administrative user interface.

location

The location into which the web items should be placed.

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 location 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 section 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="pushToTop" value="true" />
<param name="pushToTop">true</param>

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

1
2
webSectionProviderModuleDescriptor.getParams().get("pushToTop"); // returns true

Example

Providing web sections for admin pages

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

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

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

with a starter implementation of the WebSectionProvider interface:

1
2
package com.example;

import com.atlassian.plugin.web.api.WebSection;
import com.atlassian.plugin.web.api.descriptors.WebSectionProviderModuleDescriptor;
import com.atlassian.plugin.web.api.provider.WebSectionProvider;

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

import static java.util.Collections.singleton;

public class MyWebSectionProvider implements WebSectionProvider {
    private boolean pushToTop;
    private String location;

    @Override
    public void init(@Nonnull final WebSectionProviderModuleDescriptor<WebSectionProvider> moduleDescriptor) {
        this.pushToTop = moduleDescriptor.getParams().get("pushToTop");
        this.location = moduleDescriptor.getLocation();
    }

    @Override
    public Iterable<WebSection> getSections(Map<String, Object> context) {
        return singleton(new WebSection() {
            @Nonnull
            @Override
            public String getLocation() {
                return location;
            }

            @Nonnull
            @Override
            public String getWeight() {
                return pushToTop ? 0 : 10_000;
            }
            
            // rest of implementation
        });
    }
}

Plugin Modules Web Section Plugin Module

Rate this page: