Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Client Web Item Plugin Module

Introduction

Client Web Items are part of Bitbucket Data Center's Client Web Fragment family of modules. They parallel the functionality of Web Items, but are rendered dynamically in the browser.

Configuration

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

Attributes

Name	Required	Description	Default
key	Yes	The identifier of the plugin module. This key must be unique within the plugin where it is defined.	N/A
name		The human-readable name of the plugin module. I.e. the human-readable name of the web item.	N/A
section	Yes	Location into which this web item 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.	N/A
weight		Determines the order in which web items appear. Items are displayed in order of ascending weight. The 'lightest' weight is displayed first, the 'heaviest' weight sink to the bottom.	1000

Elements

Name	Required	Description	Default	Default type
condition		Defines a condition (evaluated on the server during page render) that must be satisfied for the web item to be displayed. For details on using conditions, see Web Fragments - Conditions.	N/A	N/A
conditions		Defines the logical operator type to evaluate its condition elements (evaluated on the server during page render). By default 'AND' will be used.	N/A	N/A
context-provider		Defines the data that will be passed to your client-web-panel's "js" type fields. This acts similarly to how it would on a normal web-item (see Web Item - Context provider), but there will be no incoming context object passed to the ContextProvider.	N/A	N/A
client-condition		Defines a JS function that is evaluated before each display of the client-web-panel. if the function returns true, the client-web-panel will be displayed. NOTE: client-conditions should not be used for hiding sensitive data. See the Security Note on client web fragments for details.	N/A	js
client-context-provider		Defines a JS function for transforming the data that will be passed to your client-web-panel's "js" type fields.	N/A	js
dependency		Defines a Web Resource that this client-web-item depends on.	N/A	N/A
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.	N/A	N/A
icon		Defines an icon to display with or as the link. Note: In some cases the icon element is required. Try adding it if your web section is not displaying properly.	N/A	N/A
label	Yes	The textual representation of the link. The 'key' attribute can be specified to declare a localisation key for the value instead of text in the element body.	N/A	text
link		Defines where the web item should link to. The contents of the link element will be rendered using Velocity, allowing you to put dynamic content in links. For more complex examples of links, see below.	N/A	text
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. These will be merged into the context.	N/A	text
styleClass		Defines an additional CSS class that may be added to this web item when it is rendered on the page. Note that this value may be ignored in some situations.	N/A	text
tooltip		The text representation used for mouse-over text for the link. Note that this value may be ignored in some situations.	N/A	text

Example

Here is an example atlassian-plugin.xml file containing a client web item and its dependencies:

1
2
<atlassian-plugin name="My Plugin" key="example.plugin" plugins-version="2">
    <plugin-info>
        <description>A basic plugin</description>
        <vendor name="My Company" url="http://www.mycompany.com"/>
        <version>1.0</version>
    </plugin-info>

    <client-web-item key="myWebItem" name="A Web Item" section="web-item-location" weight="100">
        <context-provider class="com.mycompany.example.plugin.PrivateWidgetsContextProvider" />
        <client-condition>WidgetManager.hasWidgets</client-condition>
        <label>Repository widgets</label>
        <link>/plugins/servlet/widgets</link>
        <dependency>example.plugin:widget-manager-js</dependency>
    </client-web-item>

    <web-resource key="widget-manager-js" name="JS for managing widgets">
        <resource type="download" name="widget-manager.js" location="js/widget-manager.js" />
    </web-resource>
</atlassian-plugin>

And the corresponding com.mycompany.example.plugin.PrivateWidgetsContextProvider:

1
2
package com.mycompany.example.plugin;

import com.atlassian.plugin.PluginParseException;
import com.atlassian.plugin.web.ContextProvider;
import com.atlassian.bitbucket.user.ApplicationUser;
import com.google.common.collect.ImmutableMap;

import java.util.Map;

public class PrivateWidgetsContextProvider implements ContextProvider {

    private WidgetService widgetService;

    public PrivateWidgetsContextProvider(WidgetService widgetService) {
        this.widgetService = widgetService;
    }

    @Override
    public void init(Map<String, String> params) throws PluginParseException {
    }

    @Override
    public Map<String, Object> getContextMap(Map<String, Object> context) {
        return ImmutableMap.<String, Object>builder()
                .put("widgets", widgetService.getWidgetsForUser((ApplicationUser) context.get('currentUser')))
                .build();
    }
}

And the corresponding widget-manager.js:

1
2
var WidgetManager = {
    hasWidgets : function(context) {
        var widgets = context.widgets;
        return widgets && widgets.length > 0;
    }
};