Package com.polarion.alm.shared.api.model.rp.widget

Class RichPageWidget

java.lang.Object

com.polarion.alm.shared.api.model.rp.widget.RichPageWidget

public abstract class RichPageWidget
extends Object

Rich Page Widget is a visual component which can be added by the user to the Rich Page and which shows some data based on user defined parameters - see getParametersDefinition(ParameterFactory) Implementations should be state-less and not assume that only one instance is created in runtime.

Since:

3.9.0

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ATTRIBUTE_ACTION_ID	Attribute for storing the action ID.
static final String	ATTRIBUTE_CONFIRM_BUTTON	Optional attribute for configuring the label of the confirmation button in the confirmation dialog.
static final String	ATTRIBUTE_CONFIRM_KEY	Optional attribute for configuring the key for remembering the state of the "Don't show this again." The check-box is not shown when the attribute is not defined or the value is empty.
static final String	ATTRIBUTE_CONFIRM_TEXT	Optional attribute for configuring the text of the confirmation dialog.
static final String	ATTRIBUTE_CONFIRM_TITLE	Optional attribute for configuring the title of the confirmation dialog.
static final String	PARAMETER_ADVANCED	Common ID used for the "Advanced" CompositeParameter

Constructor Summary

Constructors

Constructor	Description
RichPageWidget()

Method Summary

Modifier and Type	Method	Description
void	executeAction(RichPageWidgetActionContext context)	This method is executed on server after user clicks (in view mode of the page) on some HTML element inside the widget which has not empty value in attribute data-action-id (ATTRIBUTE_ACTION_ID).
String	getDescriptionHtml(RichPageWidgetContext widgetContext)	Override this method to return additional description for current widget.
abstract String	getDetailsHtml(RichPageWidgetContext widgetContext)
abstract String	getIcon(RichPageWidgetContext widgetContext)
abstract String	getLabel(SharedContext context)	Plain text label of this widget.
abstract ReadOnlyStrictMap<String,RichPageParameter>	getParametersDefinition(ParameterFactory factory)	Returned map defines the parameters for this widget. The parameter IDs (the keys in the map) must not contain the dot ('.') character. The parameters are cloned before they are used for the concrete widget instance when it is either used of the first time or before the parameters are initialized from persistence The returned parameters can already contain default values.
InputStream	getResourceStream(String path)	Use RichPageWidgetContext.resourceUrl(String) to create the relative URL to the servlet which calls this method to serve the (static) resource.
Iterable<String>	getTags(SharedContext context)	Returns tags for filtering in the widgets sidebar. The standard localized tags can be obtained by calling context.localization().getString() with one of the following values (or similar ones which will be added in the future): richpages.widget.tag.generic richpages.widget.tag.charts richpages.widget.tag.planning richpages.widget.tag.scripting richpages.widget.tag.workitems richpages.widget.tag.testRuns
boolean	isInline()	Return true, when this widget is "inline" meaning that it can be inserted inside the text paragraph
boolean	isRestricted()	Override this method to set if the widget is restricted.
void	processParameterDependencies(RichPageWidgetDependenciesContext context)	This method allows widget developer to change configurations of some parameters based on values of some other parameters.
abstract String	renderHtml(RichPageWidgetRenderingContext context)	Main method of the widget which renders the widget's HTML which is shown in the page.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

PARAMETER_ADVANCED

public static final String PARAMETER_ADVANCED

Common ID used for the "Advanced" CompositeParameter

See Also:

• Constant Field Values

ATTRIBUTE_ACTION_ID

public static final String ATTRIBUTE_ACTION_ID

Attribute for storing the action ID.

Since:

3.9.2

See Also:

• executeAction(RichPageWidgetActionContext)
• Constant Field Values

ATTRIBUTE_CONFIRM_TITLE

public static final String ATTRIBUTE_CONFIRM_TITLE

Optional attribute for configuring the title of the confirmation dialog.

Since:

3.9.2

See Also:

• executeAction(RichPageWidgetActionContext)
• Constant Field Values

ATTRIBUTE_CONFIRM_TEXT

public static final String ATTRIBUTE_CONFIRM_TEXT

Optional attribute for configuring the text of the confirmation dialog.

Since:

3.9.2

See Also:

• executeAction(RichPageWidgetActionContext)
• Constant Field Values

ATTRIBUTE_CONFIRM_BUTTON

public static final String ATTRIBUTE_CONFIRM_BUTTON

Optional attribute for configuring the label of the confirmation button in the confirmation dialog. Default label OK (localized) is used when the attribute is not defined or the value is empty.

Since:

3.9.2

See Also:

• executeAction(RichPageWidgetActionContext)
• Constant Field Values

ATTRIBUTE_CONFIRM_KEY

public static final String ATTRIBUTE_CONFIRM_KEY

Optional attribute for configuring the key for remembering the state of the "Don't show this again." The check-box is not shown when the attribute is not defined or the value is empty. The key should start with your company's name space prefix to avoid name conflicts.

Since:

3.9.2

See Also:

• executeAction(RichPageWidgetActionContext)
• Constant Field Values

Constructor Details

RichPageWidget

public RichPageWidget()

Method Details

isInline

public boolean isInline()

Return true, when this widget is "inline" meaning that it can be inserted inside the text paragraph

getIcon

@NotNull
public abstract String getIcon(@NotNull
 RichPageWidgetContext widgetContext)

getLabel

@NotNull
public abstract String getLabel(@NotNull
 SharedContext context)

Plain text label of this widget.

getDetailsHtml

@NotNull
public abstract String getDetailsHtml(@NotNull
 RichPageWidgetContext widgetContext)

getDescriptionHtml

@NotNull
public String getDescriptionHtml(@NotNull
 RichPageWidgetContext widgetContext)

Override this method to return additional description for current widget.

Returns:

empty string

Since:

3.10.2

isRestricted

public boolean isRestricted()

Override this method to set if the widget is restricted. (It can execute js or similar.) The default is false. If true, it will be checked against the 'com.polarion.restrictedWidgets.modify' permission so the usage can be disabled for lower privileged users.

Since:

3.25.6

getTags

@NotNull
public Iterable<String> getTags(@NotNull
 SharedContext context)

Returns tags for filtering in the widgets sidebar.

The standard localized tags can be obtained by calling context.localization().getString() with one of the following values (or similar ones which will be added in the future):

richpages.widget.tag.generic
richpages.widget.tag.charts
richpages.widget.tag.planning
richpages.widget.tag.scripting
richpages.widget.tag.workitems
richpages.widget.tag.testRuns

Since:

3.9.1

getParametersDefinition

@NotNull
public abstract ReadOnlyStrictMap<String,RichPageParameter> getParametersDefinition(@NotNull
 ParameterFactory factory)

Returned map defines the parameters for this widget.
The parameter IDs (the keys in the map) must not contain the dot ('.') character.

The parameters are cloned before they are used for the concrete widget instance when it is either used of the first time or before the parameters are initialized from persistence

The returned parameters can already contain default values.

renderHtml

@NotNull
public abstract String renderHtml(@NotNull
 RichPageWidgetRenderingContext context)

Main method of the widget which renders the widget's HTML which is shown in the page.

See Also:

• for details about how to correctly use it in rendering of the widgets.

getResourceStream

@NotNull
@GwtIncompatible
public InputStream getResourceStream(@NotNull
 String path)
                              throws IOException

Use RichPageWidgetContext.resourceUrl(String) to create the relative URL to the servlet which calls this method to serve the (static) resource.

Note: Requested resource might be cached by browser, so in that case this method will not be called. In other words the requested resource will not be updated on client side until the cached resource invalidates or will be removed from browser cache.

Throws:

IOException - in case that resource cannot be served.

processParameterDependencies

public void processParameterDependencies(@NotNull
 RichPageWidgetDependenciesContext context)

This method allows widget developer to change configurations of some parameters based on values of some other parameters.

This method is called on server after any parameter which was marked as RichPageParameter.Builder.dependencySource(boolean) was changed by user on the client side. It is also called before showing the parameter editors in the sidebar and before calling the renderHtml(RichPageWidgetRenderingContext)

Changes to parameters which were not marked as RichPageParameter.Builder.dependencySource(boolean) are silently ignored.

Configuration of the parameters can be changed using the Setter interfaces. For example BooleanParameter.Setter returned by BooleanParameter.set() method.

Since:

3.9.2

See Also:

• RichPageParameter.Builder.dependencySource(boolean)
• RichPageParameter.Builder.dependencyTarget(boolean)

executeAction

public void executeAction(@NotNull
 RichPageWidgetActionContext context)

This method is executed on server after user clicks (in view mode of the page) on some HTML element inside the widget which has not empty value in attribute data-action-id (ATTRIBUTE_ACTION_ID). This element can be created by the renderHtml(RichPageWidgetRenderingContext) method.

This method is also executed on server after calling the JavaScript function executeWidgetAction on the client side. See PublicJS.executeWidgetAction(Node, boolean, String) for details.

This method can persist some changes because it is executed in WriteTransaction which can be accessed by RichPageWidgetActionContext.transaction()

Confirmation dialog is displayed before the action is executed if the same HTML element as mentioned above contains not empty value in at least one of the following attributes:
data-confirm-title (ATTRIBUTE_CONFIRM_TITLE)
data-confirm-text (ATTRIBUTE_CONFIRM_TEXT)

Following attributes can be used to further configure the confirmation dialog:
data-confirm-button (ATTRIBUTE_CONFIRM_BUTTON)
data-confirm-key (ATTRIBUTE_CONFIRM_KEY)

What should happen on the client after the action is executed can be set by the following methods:
RichPageWidgetActionContext.message(String)
RichPageWidgetActionContext.executeJavaScript(String)
RichPageWidgetActionContext.replaceWithHtml(String)
RichPageWidgetActionContext.refresh(boolean)

Since:

3.9.2