Widget Development Documentation

Tags: development widgets Wiki

This page provides a guide for Widget development, describing the main widget-defining classes with examples.

Quickstart Guide

See Widget Development and Deployment QuickStart Guide for a working widget project.

The widget framework introduced in codebeamer release 8.0 aims to simplify the development of new widgets and, at the same time, offers much freedom for widget developers.

The following classes define a widget in the system:

Widget interface
WidgetInformation interface
Renderer interfacefor the Widget content and for the Editor content. (Highly recommended)
WidgetFactory interface

The implementation examples use the Spring dependency injection mechanism.

It is mandatory to annotate the Widget, WidgetInformation and WidgetFactory implementations with @Component, otherwise, the widget framework does not pick up the custom widget.

The following sections show how to implement these interfaces through annotated code examples.

WidgetInformation Interface

WidgetInformation interface class represents the widget in the widget catalog. It directly affects what is displayed in the Widget Browser popup.


package com.intland.codebeamer.dashboard.component.widgets.wiki;

import org.springframework.stereotype.Component;

import com.intland.codebeamer.dashboard.component.common.interfaces.WidgetInformation;
import com.intland.codebeamer.dashboard.component.widgets.common.WidgetCategory;

// Annotation required to make it available in the system.
@Component
public class WikiMarkupWidgetInformation implements WidgetInformation {

    // Defines the category, which affects on which tab in Widget popup it appears.
    //Possible values: ALL, CHART, PROJECT,  AGILE, TEST, PERSONAL_CONTENT, OTHER
    @Override
    public String getCategory() {
        return WidgetCategory.OTHER.getName();
    }

    // Custom icon for the Widget.
    @Override
    public String getImagePreviewUrl() {
        return "/images/newskin/dashboard/thumbnails/icon_wiki_markup.png";
    }

    // Knowledgebase url on codebeamer.com, reserved for built-in widgets.
    @Override
    public String getKnowledgeBaseUrl() {
        return "";
    }

    // Vendor information.
    @Override
    public String getVendor() {
        return "Intland";
    }

    // Key in ApplicationResources.properties, which defines the short name of the Widget.
    @Override
    public String getName() {
        return "dashboard.wiki.markup.widget.name";
    }

    // Key in ApplicationProperties.properties, which contains the description for the Widget.
    @Override
    public String getShortDescription() {
        return "dashboard.wiki.markup.widget.short.description";
    }

    // Reserved for future use.
    @Override
    public WikiMarkupWidgetFactory getFactory() {
        return null;
    }

    // Type name of the related Widget class.
    @Override
    public String getType() {
        return WikiMarkupWidget.class.getCanonicalName();
    }

}

The implementation of this interface is the hearth of any widget.

It represents the widget in the persistence layer of the framework, and also contains the logic which renders the content and editor.

Instead of the direct implementation, the inheritance from the AbstractWidget class is recommended, which already has the implementation for common features.

The interfaces:


package com.intland.codebeamer.dashboard.component.common.interfaces;

import com.intland.codebeamer.dashboard.component.common.RenderingContext;

public interface LayoutComponent {

    // Unique identifier of the component
    String getId();

    // Renders the component as HTML fragment (not a standalone HTML page)
    String renderToHtml(RenderingContext renderingContext);

}


package com.intland.codebeamer.dashboard.component.common.interfaces;

import java.util.Map;

import com.intland.codebeamer.dashboard.component.common.RenderingContext;
import com.intland.codebeamer.dashboard.component.serializer.JacksonSerializableObject;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttribute;

public interface Widget extends LayoutComponent, JacksonSerializableObject {

    // Renders the editor for the Widget as HTML fragment (not a standalone HTML page)
    String renderEditorToHtml(RenderingContext renderingContext);

    // Attributes of the widget. These are typed values, which might represent just a simple text or more complex entities like a list of projects.
    Map<String, WidgetAttribute> getAttributes();

    // Setter for the title of the Widget.
    void setTitle(String title);

    // Reserved for future use.
    void setFullWidth(boolean isFullWidth);

    // Reserved for future use.
    boolean isFullWidth();

    // Sets the color of the Widget header.
    void setColor(String color);

    // Reserved for future use.
    void setHeaderHidden(boolean headerHidden);

    // Returns a key from ApplicationResources.properties, which defines the default title for the Widget.
    String getDefaultTitleKey();
}

The AbstractWidget class:


package com.intland.codebeamer.dashboard.component.widgets.common;

import java.util.Map;

import org.apache.commons.lang3.Validate;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
import com.intland.codebeamer.dashboard.component.common.interfaces.Widget;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttribute;
// Important to have these annotations to ensure that the persistence layer saves the Widget properly
@JsonIgnoreProperties(ignoreUnknown = true)
@JsonPropertyOrder(alphabetic = true)
public abstract class AbstractWidget implements Widget {

    protected static final String NULL_MESSAGE_FORMAT = "The value %s must not be null.";

    // Identifier of the Widget
    protected final String id;
    // CURRENT attributes of the widget
    protected final Map<String, WidgetAttribute> attributes;
    // Title of the widget
    protected String title;
    // Reserved for future use
    protected boolean isFullWidth;
    // Color of the header
    protected String color;
    // Reserved for future use.
    protected boolean headerHidden;

    public AbstractWidget(String id, Map<String, WidgetAttribute> attributes) {
        Validate.notBlank(id, NULL_MESSAGE_FORMAT, "id");
        Validate.notNull(attributes, NULL_MESSAGE_FORMAT, "attributes");

        this.id = id;
        this.attributes = attributes;
    }

    // Getters and setter omitted.
}

Example:


package com.intland.codebeamer.dashboard.component.widgets.wiki;

import java.util.HashMap;
import java.util.Map;

import org.apache.commons.lang3.Validate;

import com.fasterxml.jackson.annotation.JacksonInject;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
import com.intland.codebeamer.dashboard.component.common.RenderingContext;
import com.intland.codebeamer.dashboard.component.common.interfaces.Renderer;
import com.intland.codebeamer.dashboard.component.widgets.common.AbstractWidget;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.TextAttribute;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttribute;


@JsonIgnoreProperties(ignoreUnknown = true)
@JsonPropertyOrder(alphabetic=true)
public class WikiMarkupWidget extends AbstractWidget {

    public static final String MARKUP_ATTRIBUTE_NAME = "markup";
    public static final WidgetAttribute<String> DEFAULT_MARKUP_ATTRIBUTE = new TextAttribute("", true, false);

    // Preferred method to define default attributes
    public static Map<String, WidgetAttribute> getDescriptor() {
        final Map<String, WidgetAttribute> result = new HashMap<String, WidgetAttribute>();

        result.put(MARKUP_ATTRIBUTE_NAME, DEFAULT_MARKUP_ATTRIBUTE);

        return result;

    }

    // Renderer instance, which can create the content of the Widget
    private final Renderer<WikiMarkupWidget> htmlRenderer;
    // Renderer instance, which can create the editor form for the Widget
    private final Renderer<WikiMarkupWidget> editorRenderer;
    // Annotated constructor used by the persistence layer. Do not forget to add these annotations!
    public WikiMarkupWidget(@JsonProperty("id") final String id, @JsonProperty("attributes") final Map<String, WidgetAttribute> attributes,
            @JacksonInject("wikiMarkupWidgetHtmlRenderer") final Renderer<WikiMarkupWidget> htmlRenderer,
            @JacksonInject("wikiMarkupWidgetEditorRenderer") final Renderer<WikiMarkupWidget> editorRenderer) {
        super(id, attributes);

        Validate.notNull(htmlRenderer, NULL_MESSAGE_FORMAT, "htmlRenderer");
        Validate.notNull(editorRenderer, NULL_MESSAGE_FORMAT, "editorRenderer");

        this.htmlRenderer = htmlRenderer;
        this.editorRenderer = editorRenderer;
    }

    @Override
    public String getTypeName() {
        return WikiMarkupWidget.class.getCanonicalName();
    }

    // Recommended way to render the content of the Widget.
    @Override
    public String renderToHtml(final RenderingContext renderingContext) {
        return htmlRenderer.render(renderingContext, this);
    }

    // Recommended way to render the editor for of the Widget.
    @Override
    public String renderEditorToHtml(final RenderingContext renderingContext) {
        return editorRenderer.render(renderingContext, this);
    }

    @Override
    public String getDefaultTitleKey() {
        return "dashboard.wiki.markup.widget.name";
    }
}

The above example shows how a widget can be implemented from scratch.

It is recommended, however, to extend the AbstractRendererWidget class which already implements this pattern, and contains an important error handling code as well.

WidgetAttribute Subtypes as Supporting Classes

The subtypes of this generic class represent the different data types which can be used as the parameters of widgets.

All the built-in subtypes have their own renderer which, coupled with some other supporting classes, make it possible to generate the editor forms for each widget automatically.

The class:


package com.intland.codebeamer.dashboard.component.widgets.common.attribute;

import java.util.Map;

import org.apache.commons.lang3.Validate;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
// Important annotations, which fine the persistence mechanism.
@JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include=JsonTypeInfo.As.PROPERTY, property="typeName")
@JsonIgnoreProperties(ignoreUnknown = true)
@JsonPropertyOrder(alphabetic=true)
public abstract class WidgetAttribute<T> {

    protected static final String NULL_MESSAGE_FORMAT = "The value %s must not be null.";

    // CURRRENT value of the attribute.
    @JsonTypeInfo(use=JsonTypeInfo.Id.CLASS, include=JsonTypeInfo.As.WRAPPER_OBJECT, property="valueTypeName")
    T value;
    // Shows whether this attribute has to be filled on the editor form.
    protected final boolean required;
    // Shows whether this attribute has to be validated using additional validation logic.
    protected final boolean validationRequired;

    public WidgetAttribute(final T value, final boolean required, final boolean validationRequired) {
        Validate.notNull(value, NULL_MESSAGE_FORMAT, "value");

        this.value = value;
        this.required = required;
        this.validationRequired = validationRequired;
    }
    // Getters and setters omited.
    // Important method, all attributes has to provide a way to parse values from a String representation.
    public abstract WidgetAttribute<T> convert(final String newValue);

    // If the attribute is affected by export / import mechanism (like using project ids), then the identifiers will be mapped by calling this method during the import.
    public void replaceIdsAfterImport(Map<Integer, Map<Integer, Integer>> ids) {

    }

    protected void setValue(T value) {
        this.value = value;
    }

}

Simple subtypes:

Class name	Value type
`BooleanAttribute`	boolean
`StringAttribute`	string
`TextAttribute`	string, but has a rich text editor
`IntegerAttribute`	integer
`IntegerListAttribute`	list of integers
`StringListAttribute`	list of strings
`FixedChoiceWidgetAttribute`	Can be used with an enum as type parameter, contains a single value from that enum.
`MultiChoiceWidgetAttribute`	Similar to `FixedChoiceWidgetAttribute`, but can contain more than one value.

Subtypes representing codebeamer entities:

Class name	Value type
`ProjectListAttribute`	list of project identifiers
`ProjectAttribute`	single project identifier
`ReleaseListAttribute`	list of release identifiers
`ReleaseAttribute`	single release identifier
`TeamListAttribute`	list of team identifiers
`TeamAttribute`	single team identifier
`TrackerListAttribute`	list of tracker identifiers
`TrackerAttribute`	single tracker identifier
`TrackerTypeListAttribute`	list of `TrackerType` identifiers
`TypedTrackerListAttribute`	similar to `TrackerListAttribute`, but only allows the given tracker types
`UserListAttribute`	list of user identifiers
`UserAttribute`	single user identifier

Renderer Interface and Implementations

Providing content through Renderer instances is the preferred way in widget framework.

As seen in the last example code, it allows to write a clean and straightforward widget class by moving the potentially complex tasks of rendering the widget content and editor forms to a standalone class.


import com.intland.codebeamer.dashboard.component.common.RenderingContext;

public interface Renderer<T> {

    String render(RenderingContext renderingContext, T object);
}

The render method creates a String value based on the current RenderingContext and given object.

The interface, by design, does not enforce any technical solutions to create the String representation of the object. Developers can use either template-based or programmatic rendering, depending on their preferences or specifications.

The HTML content renderer has one restriction: the custom code must be wrapped in a DIV element which contains the identifier of the widget, as in the following velocity template:

<div id="${id}">
${html}
</div>

An implementation:


package com.intland.codebeamer.dashboard.component.widgets.wiki;

//  Imports removed

@Component
@Qualifier("wikiMarkupWidgetHtmlRenderer")
public class WikiMarkupWidgetHtmlRenderer implements Renderer<WikiMarkupWidget> {

    private static final String TEMPLATE = "wikimarkup-widget.vm";

    @Autowired
    private WikiPageManager wikiPageManager;
    @Autowired
    private WikiMarkupProcessor wikiMarkupProcessor;

    @Override
    public String render(final RenderingContext renderingContext, final WikiMarkupWidget object) {
        // Initialization and argument checks (omitted)

        // Use the arguments to retrieve the information required to render the wiki markup to html.
        final String id = object.getId();
        final Map<String, WidgetAttribute>  attributes = object.getAttributes();
        final WidgetAttribute wikiMarkupAttribute = attributes.get(WikiMarkupWidget.MARKUP_ATTRIBUTE_NAME);
        final String markup = wikiMarkupAttribute.getValue() != null ? (String) wikiMarkupAttribute.getValue() : "";

       // Transforming Wiki markup to HTML (omitted)

        // Add data to Velocity context
        velocityContext.put("id", id);
        velocityContext.put("html", html);

        final TemplateRenderer templateRenderer = TemplateRenderer.getInstance();

        // Render Velocity template
        return templateRenderer.renderTemplateOnPath(TEMPLATE, velocityContext, new Parameters(renderingContext.getRequest().getLocale(), false));
    }

    // Helper methods (omitted)

}

Rendering the content of the editor form can be simplified by using support classes. These classes render the editor based on the attributes of the widget and the standard renderer, which creates the proper form element for each attribute.

All built-in WidgetAttribute types has their specific render.

An implementation based on velocity template

Using velocity is mandatory in this type of Renderer implementations.


package com.intland.codebeamer.dashboard.component.widgets.wiki;

import org.apache.commons.lang3.Validate;
import org.apache.velocity.VelocityContext;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;

import com.intland.codebeamer.dashboard.component.common.RenderingContext;
import com.intland.codebeamer.dashboard.component.common.interfaces.Renderer;
import com.intland.codebeamer.dashboard.component.widgets.common.ModelPopulator;
import com.intland.codebeamer.utils.TemplateRenderer;
import com.intland.codebeamer.utils.TemplateRenderer.Parameters;


@Component
@Qualifier("wikiMarkupWidgetEditorRenderer")
public class WikiMarkupWidgetEditorRenderer implements Renderer<WikiMarkupWidget> {

    private static final String NULL_MESSAGE_FORMAT = "The value %s must not be null.";
    private static final String EDITOR_TEMPLATE = "wikimarkup-widget-editor.vm";

    // This is the required helper class, which will generate the editor form elements
    private final ModelPopulator<VelocityContext> modelPopulator;
    private final TemplateRenderer templateRenderer;

    @Autowired
    public WikiMarkupWidgetEditorRenderer(final ModelPopulator<VelocityContext> modelPopulator, final TemplateRenderer templateRenderer) {
        Validate.notNull(modelPopulator, NULL_MESSAGE_FORMAT, "modelPopulator");
        Validate.notNull(templateRenderer, NULL_MESSAGE_FORMAT, "templateRenderer");

        this.modelPopulator = modelPopulator;
        this.templateRenderer = templateRenderer;
    }


    @Override
    public String render(final RenderingContext renderingContext, final WikiMarkupWidget wikiMarkupWidget) {
        Validate.notNull(renderingContext, NULL_MESSAGE_FORMAT, "renderingContext");
        Validate.notNull(wikiMarkupWidget, NULL_MESSAGE_FORMAT, "wikiMarkupWidget");

        // Create the Velocity context
        final VelocityContext velocityContext = new VelocityContext();

        // Let the populator create the right HTML fragments for each attribute
        modelPopulator.populateAttributes(renderingContext, wikiMarkupWidget, WikiMarkupWidget.getDescriptor(), velocityContext);

        // Return the rendererd template
        return templateRenderer.renderTemplateOnPath(EDITOR_TEMPLATE, velocityContext, new Parameters(renderingContext.getRequest().getLocale(), false));
    }

}

The ModelPopulator adds each form element to the VelocityContext with the name defined by the descriptor of the widget (WikiMarkupWidget.getDescriptor() in this case). The template is the following:

${markup}
<br/>

Although, the form elements are generated, own contents can still be added through this template.

RenderingContext Implementation

RenderingContext instance holds data, which might be useful when rendering HTML content.


// Imports omitted

public class RenderingContext {

    // The current user, who is viewing or editing the dashboard.
        private final UserDto user;
    // The current request instance.
    private final HttpServletRequest request;
    // WikiPageDto representing the actual Dashboard.
    private final WikiPageDto dashboard;
    // Utility class, which can be used to translate keys from ApplicationResources.properties to text
    private final LocalizedTextRetriever localizedTextRetriever;

    // Constructor, getters omitted

}

WidgetFactory Interface

The implementations of the WidgetFactory interface are used to create new instances of widgets while loading a dashboard form the persistence layer, and creating or editing widgets.


package com.intland.codebeamer.dashboard.component.serializer;

import com.fasterxml.jackson.databind.InjectableValues;

public interface JacksonObjectDeserializeContext<T> {
    // Class of the Widget
    Class<T> getType();
    // Full class name of the Widget
    String getTypeName();
    // All the properties, which must be injected through dependency injection into Widgets. (See the Jackson annotation on the example Widget constructor.)
    InjectableValues getInjectableValues();

}


package com.intland.codebeamer.dashboard.component.common.interfaces;

import com.intland.codebeamer.dashboard.component.serializer.JacksonObjectDeserializeContext;

// Marker interface
public interface LayoutComponentFactory<T extends LayoutComponent>  extends JacksonObjectDeserializeContext<T> {

}


package com.intland.codebeamer.dashboard.component.common.interfaces;

import java.util.Map;

public interface WidgetFactory<T extends Widget> extends LayoutComponentFactory<T> {

    // Create an instance with the given attributes
    T createInstance(String id, Map<String, String> attributes);

    // Create an instance with the given attributes, run validations
    T createInstance(String id, Map<String, String> attributes, boolean validate);

    // Create an instance with default attribute values
    T createInstance();

}

An implementation example:


package com.intland.codebeamer.dashboard.component.widgets.wiki;

import java.util.Map;
import java.util.UUID;

import org.apache.commons.lang3.Validate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;

import com.fasterxml.jackson.databind.InjectableValues;
import com.intland.codebeamer.dashboard.component.common.interfaces.Renderer;
import com.intland.codebeamer.dashboard.component.common.interfaces.WidgetFactory;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttribute;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttributeMapper;


@Component
public class WikiMarkupWidgetFactory implements WidgetFactory<WikiMarkupWidget> {

    private static final String NULL_MESSAGE_FORMAT = "The value %s must not be null.";

    // The HMTL renderer
    private final Renderer<WikiMarkupWidget> htmlRenderer;
    // The editor form renderer
    private final Renderer<WikiMarkupWidget> editorRenderer;
    private final WidgetAttributeMapper widgetAttributeMapper;

    // Qualifiers are important here!
    @Autowired
    public WikiMarkupWidgetFactory(@Qualifier("wikiMarkupWidgetHtmlRenderer") final Renderer<WikiMarkupWidget> htmlRenderer,
            @Qualifier("wikiMarkupWidgetEditorRenderer") final Renderer<WikiMarkupWidget> editorRenderer,
            final WidgetAttributeMapper widgetAttributeMapper) {
        Validate.notNull(htmlRenderer, NULL_MESSAGE_FORMAT, "htmlRenderer");
        Validate.notNull(editorRenderer, NULL_MESSAGE_FORMAT, "editorRenderer");
        Validate.notNull(widgetAttributeMapper, NULL_MESSAGE_FORMAT, "widgetAttributeMapper");

        this.htmlRenderer = htmlRenderer;
        this.editorRenderer = editorRenderer;
        this.widgetAttributeMapper = widgetAttributeMapper;
    }

    @Override
    public WikiMarkupWidget createInstance(String id, Map<String, String> attributes) {
        return createInstance(id, attributes, true);
    }

    @Override
    public WikiMarkupWidget createInstance(String id, Map<String, String> attributes, boolean validate) {
        Validate.notBlank(id, NULL_MESSAGE_FORMAT, "id");
        Validate.notNull(attributes, NULL_MESSAGE_FORMAT, "attributes");

        final Map<String, WidgetAttribute> widgetAttributes = widgetAttributeMapper.map(attributes, WikiMarkupWidget.getDescriptor(), validate);

        return new WikiMarkupWidget(id, widgetAttributes, htmlRenderer, editorRenderer);
    }
    // The default attributes of the Widget are accessed via a static method
    @Override
    public WikiMarkupWidget createInstance() {
        return new WikiMarkupWidget(UUID.randomUUID().toString(), WikiMarkupWidget.getDescriptor(), htmlRenderer, editorRenderer);
    }

    @Override
    public Class<WikiMarkupWidget> getType() {
        return WikiMarkupWidget.class;
    }


    @Override
    public String getTypeName() {
        return WikiMarkupWidget.class.getCanonicalName();
    }
    // Add all the constructor attributes of the Widget class, which needs to be injected via dependency injection. Make sure that the name of the value here matches the Jackson annotation on the Widget itself! ("wikiMarkupWidgetHtmlRenderer" for example)
    @Override
    public InjectableValues getInjectableValues() {
        final InjectableValues inject = new InjectableValues.Std()
        .addValue("wikiMarkupWidgetHtmlRenderer", htmlRenderer)
        .addValue("wikiMarkupWidgetEditorRenderer",editorRenderer);
        return inject;
    }

}

Wrapping Existing Wiki Plugins as Widgets

Previously written wiki plugins can be reused as widgets. Exactly the same classes are to be created for plugin-based and standalone widgets, however, there is a slight difference between them.

If a wiki plugin is intended to be used for a HTML representation, the actual parameters of the widget, as arguments to the plugin, need to be passed. Its execute method needs to be called as well to generate the HTML.
The framework offers a renderer implementation which simplifies this process. The AbstractDefaultWidgetHtmlRenderer defines a few important methods:


import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

import org.springframework.beans.factory.ObjectFactory;
import org.springframework.beans.factory.annotation.Autowired;

import com.intland.codebeamer.dashboard.component.common.interfaces.Widget;
import com.intland.codebeamer.dashboard.component.widgets.common.DefaultWidgetHtmlRenderer;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttribute;
import com.intland.codebeamer.dashboard.component.widgets.provider.WidgetAttributeValueProvider;
import com.intland.codebeamer.wiki.plugins.base.AbstractCodeBeamerWikiPlugin;


public abstract class AbstractDefaultWidgetHtmlRenderer<U extends Widget, Z extends AbstractCodeBeamerWikiPlugin> extends DefaultWidgetHtmlRenderer<U, Z>{

    @Autowired
    public AbstractDefaultWidgetHtmlRenderer(ObjectFactory<Z> factory) {
        super(factory);
    }

    protected Map<String, String> createPluginParameters(Map<String, WidgetAttribute> attributes) {
        final Map<String, String> parameters = new HashMap<String, String>();

   // Generates the parameters of the plugin using the WidgetAttributeValueProviders, code omitted


        createAdditionalParameters(attributes, parameters);

        return parameters;
    }

    // You can add any parameter here, which is not generated by a WidgetAttributeValueProvider instance
    protected void createAdditionalParameters(final Map<String, WidgetAttribute> attributes, final Map<String, String> parameters) {

    }

    // Returns the WidgetAttributes defined in the Widget itself
    protected abstract WidgetAttributeWrapper[] getWidgetAttributes();

    // A list of WidgetAttributeValueProvider instances. These can map a WidgetAttribute to a Wiki plugin parameter.
    protected Map<WidgetAttributeWrapper, WidgetAttributeValueProvider> getValueProviders() {
        return Collections.emptyMap();
    }
}

The WidgetAttributeValueProvider instances convert WidgetAttributes to string parameters according to the interface of the wiki plugin.


import java.util.Map;

import com.intland.codebeamer.dashboard.component.widgets.common.WidgetAttributeWrapper;
import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttribute;

public interface WidgetAttributeValueProvider {

    String obtainValue(WidgetAttributeWrapper attribute, Map<String, WidgetAttribute> attributes);
}

An example - converting an integer:


import com.intland.codebeamer.dashboard.component.widgets.common.attribute.WidgetAttribute;


public abstract class AbstractIntegerValueProvider extends AbstractWidgetAttributeValueProvider<WidgetAttribute<Integer>> {

    @Override
    protected String convertWidgetAttributeToString(final WidgetAttribute<Integer> widgetAttribute) {
        return widgetAttribute.getValue().toString();
    }

}

The AbstractWidgetAttributeValueProvider class has the default implementation for the obtainValuemethod, so subclasses only have to define

the convertWidgetAttributeToString and
the getWidgetAttributeKey method.

The latter should return the name of wiki plugin parameter, like for example this class:


import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;


@Qualifier("widthIntegerValueProvider")
@Component
public class WidthIntegerValueProvider extends AbstractIntegerValueProvider {

    public static final String WIDTH = "width";

    @Override
    public String getWidgetAttributeKey() {
        return WIDTH;
    }
}

Wrapping the plugin rendering within a custom renderer:


package com.intland.codebeamer.dashboard.component.widgets.project;

import java.util.HashMap;
import java.util.Map;

import org.apache.commons.lang3.Validate;
import org.springframework.beans.factory.ObjectFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;

import com.intland.codebeamer.dashboard.component.widgets.common.AbstractDefaultWidgetHtmlRenderer;
import com.intland.codebeamer.dashboard.component.widgets.common.WidgetAttributeWrapper;
import com.intland.codebeamer.dashboard.component.widgets.provider.WidgetAttributeValueProvider;
import com.intland.codebeamer.wiki.plugins.releaseganttchart.ReleaseGanttChartPlugin;


@Component
@Qualifier("releaseGanttChartWidgetHtmlRenderer")
public class ReleaseGanttChartWidgetHtmlRenderer extends AbstractDefaultWidgetHtmlRenderer<ReleaseGanttChartWidget, ReleaseGanttChartPlugin> {

    private static final String NULL_MESSAGE_FORMAT = "The value %s must not be null.";

    private final WidgetAttributeValueProvider releaseListAttributeValueProvider;
    private final WidgetAttributeValueProvider heightAttributeValueProvider;

    @Autowired
    public ReleaseGanttChartWidgetHtmlRenderer(ObjectFactory<ReleaseGanttChartPlugin> objectFactory,
            @Qualifier("ganttReleaseListAttributeValueProvider") final WidgetAttributeValueProvider releaseListAttributeValueProvider,
            @Qualifier("ganttHeightAttributeProvider") final WidgetAttributeValueProvider heightAttributeValueProvider) {
        super(objectFactory);

        Validate.notNull(releaseListAttributeValueProvider, NULL_MESSAGE_FORMAT, "releaseListAttributeValueProvider");
        Validate.notNull(heightAttributeValueProvider, NULL_MESSAGE_FORMAT, "heightAttributeValueProvider");

        this.releaseListAttributeValueProvider = releaseListAttributeValueProvider;
        this.heightAttributeValueProvider = heightAttributeValueProvider;
    }


    @Override
    protected WidgetAttributeWrapper[] getWidgetAttributes() {
        return ReleaseGanttChartWidget.Attribute.values();
    }

    @Override
    protected Map<WidgetAttributeWrapper, WidgetAttributeValueProvider> getValueProviders() {
        final Map<WidgetAttributeWrapper, WidgetAttributeValueProvider> valueProviders =
                new HashMap<WidgetAttributeWrapper, WidgetAttributeValueProvider>();

        valueProviders.put(ReleaseGanttChartWidget.Attribute.RELEASE_IDS, releaseListAttributeValueProvider);
        valueProviders.put(ReleaseGanttChartWidget.Attribute.HEIGHT, heightAttributeValueProvider);

        return valueProviders;
    }

}