Page tree
Skip to end of metadata
Go to start of metadata

Note

This topic includes references to Neptuny and Caplan. BMC TrueSight Capacity Optimization was previously known as Neptuny Caplan.

The Dashboard API comprises various methods, interfaces and classes that are responsible for carrying out a variety of portlet operations.

For detailed information on these methods, interfaces and classes, refer to the following sections:

CaplanPortletHelper interface

This interface offers useful methods for accessing the parameter framework that enables portlets to interact with themselves. To get an object of this interface, use the following method:

PortletUtils.getPortletHelper(PortletRequest, PortletResponse)

The following table lists all the methods included in the CaplanPortletHelper interface:

 

Methods included in the CaplanPortletHelper interface

Method

Description

getAllParameterMasks()

Returns an array of all ParameterMaskBean objects available for the portlet.

getCommunityId()

Returns a String object representing the ID of the current community.

getCustomParameterMaskBean(String)

Returns a ParameterMaskBean object representing a specific custom parameter; typically, custom parameters are defined by the user in portlet preferences.

getCustomParameterMasks()

Returns an array of ParameterMaskBean objects for each custom parameter available.

getCustomParameterNames()

Returns a set of String objects representing the names of the defined custom parameters.

getDefaultParameterMaskBean(String)

Returns a ParameterMaskBean object representing a specific default parameter; typically, default parameters are defined by the developer in the portlet Java class.

getDefaultParameterMasks()

Returns an array of ParameterMaskBean objects for each default parameter available.

getLogger(Class)

Returns a logger for the class.

getMessage()

Returns a MessageBean object representing a message for the user; the information can be an info, a warning or an error and can contain a list of sub-messages.

getPageId()

Returns a String object representing the full ID of the current page; this ID is composed of the community ID along with the "/" sign and a specific page identifier, for example, "3876/2"

getParameterMaskBean(String)

Returns a ParameterMaskBean object representing a specific parameter (default or custom).

getPortletPreferences()

Returns the portlet preferences for the current portlet; it returns the same object of the standard PortletRequest.getPreferences() method.

getQueryManager()

Returns a QueryManager object that can be used to perform database queries.

getQueryManager(String)

Returns a QueryManager object for a specific data source.

getQueryParameters()

Returns a QueryParameters object that contains the query timeout settings specified in portlet preferences; the default timeout is 60 seconds.

getQueryTimeout()

Returns the query timeout, in seconds, defined in portlet preferences.

getTimeFilterMaskBean()

Returns a TimeFilterMaskBean object that specifically handles the time filter parameter.

getUserPortletFilter(String, String)

Returns the value of the filter for the given portlet namespace and filter name; user-portlet filters are unique for each couple of user and portlet instance, and are commonly used to save the status of the user interaction within a specific portlet; for example, the column to sort in a View Template Table portlet.

populateEditAttributes()

Puts the common variable values in the Request object to correctly use the edit mode of a portlet.

populateViewAttributes()

puts the common variable values in the Request object to correctly use the view mode of a portlet.

registerCustomParameterMask(String, String)

Saves the mask of a specific custom parameter by specifying the parameter name and the mask.

registerCustomParameterMask(String, String, String)

Saves the mask of a specific custom parameter by specifying the parameter name, the mask and a label to be shown.

registerDefaultParameterMask(String, String)

Saves the mask of a specific default parameter by specifying the parameter name and the mask.

registerDefaultParameterMask(String, String, String)

Saves the mask of a specific default parameter by specifying the parameter name, the mask and a label to be shown.

savePortletPreferences()

Saves the current portlet preferences.

setMessage(MessageBean)

Saves a MessageBean object into the Request object.

setUserPortletFilter(String portletNamespace, String userPortletFilterName, String value)

Sets a specific user-portlet filter by specifying the portlet namespace, the filter name and the value to set.

UserFilters interface

This interface provides a set of constants to access page parameters, also called User Filters or just UF. The main, and most frequently used constants are listed in the following table:

User Filters to access page parameters

Constant

Description

COMMUNITY_UF_PREFIX

Identifies community user filters (advanced use).

GLOBAL_UF_PREFIX

Identifies global user filters (advanced use).

UF_APPID

Application User Filter identifier.

UF_CONSOLIDATION_MODEL_REFRESH

User Filter used to force the refresh of Consolidation models.

UF_CUSTOM_PREFIX

Prefix used to identify a custom UF.

UF_FOLDERID

Folder User Filter identifier.

UF_GOID

Grouping object User Filter identifier.

UF_LOCATIONID

Location User Filter identifier.

UF_PREFIX

Prefix used to identify user filters.

UF_REPGROUPID

Report group User Filter identifier.

UF_REPORTID

Report User Filter identifier.

UF_REPORTURL

Report URL User Filter identifier.

UF_RESOURCE

Resource User Filter identifier.

UF_SERIESID

Series User Filter identifier.

UF_SUBRESOURCE

Sub-resource User Filter identifier.

UF_SYSID

System User Filter identifier.

UF_SYSOBJID

System object User Filter identifier.

UF_TAGID

Tag User Filter identifier.

UF_TIMEID

Timefilter identifier.

UF_WKLDID

Business driver User Filter identifier.

UF_WKLDOBJID

Business driver object User Filter identifier.

PortletUtils class

This class provides the following utility methods:

Methods in the PortletUtils class

Method

Description

getPortletHelper(PortletRequest, PortletResponse)

Returns an object implementing the CaplanPortletHelper interface.

include(RenderRequest, RenderResponse, String, PortletConfig)

Includes the portlet page, for example, PortletUtils.include(request, response, "ViewPage", getPortletConfig());

ParameterMaskBean object

This object has the following characteristics:

  • It is returned by the PortletHelper class.
  • It allows for easy access of parameters read by the portlet.
  • It stores user preferences for parameters (for example, the choice to read or ignore a specific parameter) and returns their correct value using the getValue method.
  • It reads the correct value of a parameter from a page of specified values configured in the portlet preferences. If you configure a portlet to ignore a parameter, it returns a NULL value.

The available options for a parameter can be specified using a mask; for example, you can disable the read option for a specific parameter so that users are unable choose it. The mask can be structured in any of the following forms:

ignore|read|specified|write to page|write to community

or

ignore|read|specified::value|write to page|write to community

Each section of a mask is separated by the "|" symbol, is composed of two sets of characters, [cu] and [ed]. The mask is structured in the following way:

[cu][ed]|[cu][ed]|[cu][ed]|[cu][ed]|[cu][ed]

The following table explains the structure of the preceding string:

Mask character

Meaning

c

Checked by default

u

Unchecked by default

e

Enabled: The user can change the option of editing portlet preferences

d

disabled: The user cannot change the option of editing portlet preferences

For example, consider the following mask:

ue|ce|ue|cd|ud

The mask in this example implies the following:

  • ue: The "ignore" setting is not selected by default, but the user can choose it.
  • ce: The "read" option is selected by default and the user change it.
  • ue The "specified" option is not selected by default, but it is enabled.
  • cd: The "write to page" option is checked and the user cannot change it.
  • ud: The "write to community" option is not selected and the user cannot select it.

The following table lists all methods provided by the ParameterMaskBean class:

Methods provided by the ParameterMaskBean class

Method

Description

ParameterMaskBean()

Constructor

containsValue(String)

Returns "true" if the associated parameter contains the specified value, "false" otherwise

getLabel()

Returns the label of the associated parameter

getName()

Returns the name of the associated parameter

getValue()

Returns the value of the associated parameter; in case of multiple parameter values, it returns the first one

getValues()

Returns an array of the associated parameter values

getValuesAsString()

Returns a String object containing all parameter values, separated by the string defined by the FILTER_SEPARATOR constant

isEmptyValue()

Returns "true" if the parameter has NULL or a zero-length value, "false" otherwise

setLabel(String)

Sets the label for the associated parameter

setName(String)

Sets the name for the associated parameter

setValue(String)

Sets the value for the associated parameter; the value can be a simple string or a multi-value string, using the FILTER_SEPARATOR constant as separator

getIgnoreChecked()
getReadChecked()
getSpecifiedChecked()
getWriteToCommunityChecked()
getWriteToPageChecked()

These methods return a boolean value representing the respective option value: "true" if selected, "false" if unselected; for example, getReadChecked() returns "true" if the "read" option is selected

getIgnoreEnabled()
getReadEnabled()
getWriteToCommunityEnabled()
getSpecifiedEnabled()
getWriteToPageEnabled()

These methods return a boolean value for the status of the respective options: "true" if enabled, "false" if disabled; for example, getWriteToCommunityStatus() returns "true" if the option "write to community" is enabled

getIgnoreStatus()
getReadStatus()
getSpecifiedStatus()
getWriteToCommunityStatus()
getWriteToPageStatus()

These methods return a string representing the status of the respective option, typically to use with HTML checkboxes; for example, getWriteToPageStatus() returns "CHECKED DISABLED" if the "ignore" option is both checked and disabled

getMask()

Returns the current mask string

getMask(ParameterMaskBean)

Returns a mask that combines the current mask and the settings of the disabled options of the specified ParameterMaskBean; typically, this function is used to assure that the specified disabled options are used instead of the saved one in case of reading old-version portlet preferences

getSpecValue()

Returns the value of the "specified" option

isCustom()

Returns "true" if the object is associated with a custom parameter, "false" otherwise

setCustom(boolean)

Sets if the object is associated with a custom parameter or not

setIgnoreChecked(boolean)
setReadChecked(boolean)
setSpecifiedChecked(boolean)
setWriteToCommunityChecked(boolean)
setWriteToPageChecked(boolean)

These methods allow to select a specific option; for example, setIgnoreChecked(true) Will select the "ignore" option

setspecValue(String)

Sets a value for the "specified" option

setMask(String)

Specifies a new mask

TimeFilterMaskBean class

This class extends the ParameterMaskBean class, and offers the following additional method:

Method in the TimeFilterMaskBean class

Method

Description

isRestrictedTimeFilter()

  • Returns "true" if the timefilter contains one of these values:
    • "RESTRICTED=lm": Last month timefilter
    • "RESTRICTED=lw": Last week timefilter
    • "RESTRICTED=ld": Last day timefilter
  • Returns "false" if the timefilter contains a numeric timefilter ID

MessageBean class

This class, in conjunction with the <capdash:messages/> tag (see Portlet {{Taglib}} tag libraries), allows you to display informative messages to the user in a standard style. It can manage INFO, WARNING and ERROR messages, and provides a way to create a list of items within a message, for example, to display multiple hints.

The following table lists all methods provided by this class:

 Methods in the MessageBean class

Method

Description

MessageBean()

Constructor

addMessageItem(Object)

Adds an object to the message list

clearMessages()

Removes the message list

getErrorCount()

Returns the size of the message list

getMainMessage()

Returns the main message

getMessageList()

Returns a array of String objects for the items in the list

getType()

Returns a string representing the message type; possible values are defined in the following constants:

  • TYPE_INFO
  • TYPE_WARNING
  • TYPE_ERROR

hasMessages()

Returns "true" if the list has at least one element, "false" otherwise

setMainMessage(String)

Sets the main message

setType(String)

Sets the message type; valid options are the following constants:

  • TYPE_INFO
  • TYPE_WARNING
  • TYPE_ERROR

Portlet Taglib tag libraries

In JSP files of your portlets, you can use several portlet tag libraries (Taglib) by importing them as follows:

<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>

The tag library provides several tags to carry out a variety of operations. Here we list the most useful and commonly used tags:

The <portlet:defineObjects/> tag

This tag establishes the following three objects for use in the included portlet JSP pages:

  • renderRequest
  • renderResponse
  • portletConfig

For example:

<%@ page contentType="text/html"%>
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
...
<portlet:defineObjects/>

The <portlet:namespace/> tag

This tag returns the namespace of the current portlet.

For example:

<%@ page contentType="text/html"%>
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
...
<portlet:defineObjects />
<p> The portlet namespace is <portlet:namespace/> </p>

As the namespace is unique for each portlet instance, this tag can be efficiently used to distinguish HTML element IDs between different instances of the same portlet.
For example:

<!-- The id of the following element will be different
     for each instance of this portlet -->
<div id="mainContent<portlet:namespace/>">
   <a href="#" onClick="document.getElementById
               ('mainContent<portlet:namespace/>')
    .innerHTML = 'Changed!';">
     Click me to change. 
     Only the element of this portlet instance will be changed.
   </a>
</div>

Caplan Dashboard Taglib tag libraries

In JSP files of your portlets, you can use the Caplan Dashboard Taglib tag library by importing it as follows:

<%@ taglib uri="http://neptuny.com/portlet/tld" prefix="capdash"%>

The Caplan Dashboard Taglib tag library provides several tags to carry out a variety of Dashboard operations. Here we list the most useful and commonly used tags:

The <capdash:viewStart/> ... <capdash:viewEnd/> tag

These tags allow you to enclose the main part of a portlet view-mode JSP.

For example:

<%@ page contentType="text/html"%>
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c"%>
<%@ taglib uri="http://neptuny.com/portlet/tld" prefix="capdash"%>

<portlet:defineObjects />

<capdash:viewStart />

  ...

<capdash:viewEnd />

The <capdash:editStart/> ... <capdash:editEnd/> tag

These tags allow you to enclose the main part of a portlet edit-mode JSP.

For example:

<%@ page contentType="text/html"%>
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c"%>
<%@ taglib uri="http://neptuny.com/portlet/tld" prefix="capdash"%>
<portlet:defineObjects />

<capdash:editStart/>

  ...

<capdash:editEnd/>

The <capdash:viewForm/> tag

This tag allows you to define the main HTML form used in the view-mode JSP.

For example:

<capdash:viewStart/>

  <capdash:viewForm>
    <input type="hidden" name="myfield" value="<c:out value="${myfield}"/>"/>
  </capdash:viewForm>

<capdash:viewEnd/>

The <capdash:editForm/> tag

This tag allows you to define the main HTML form used in the edit-mode JSP.

For example:

<capdash:editStart/>

  <capdash:editForm>

    <fieldset>
	  List height: <input type="text" name="listheight" value=
          "<c:out value="${listheight}"/>" />
    </fieldset>

    <input type="submit" value="Save" name="submitEdit" class="portlet-form-button">

  </capdash:editForm>

<capdash:editEnd/>

The <capdash:parameterMask/> tag

This tag can be used within the <capdash:editForm> and </capdash:editForm> tags to display the HTML editor for the parameter options.

For example:

<capdash:editForm>

	<capdash:parameterMask/>

	...

</capdash:editForm>

The <capdash:editCustomParameters/> tag

This tag can be used within the <capdash:editForm> and </capdash:editForm> tags to display the HTML input textbox for the custom parameters.

For example:

<capdash:editForm>

  <capdash:parameterMask/>

  <capdash:editCustomParameters/>

  ...

</capdash:editForm>

The <capdash:editTimeout/> tag

This tag can be used within the <capdash:editForm> and </capdash:editForm> tags to display the HTML input textbox for the timeout option.

For example:

<capdash:editForm>

  <capdash:parameterMask/>

  <capdash:editCustomParameters/>

  ...

  <capdash:editTimeout/>

</capdash:editForm>

The <capdash:formId/> tag

This tag allows you to get the HTML ID of the forms generated by the <capdash:viewForm/> and <capdash:editForm/> tags. You can use this tag in both view-mode and edit-mode JSPs.

For example, for a view-mode JSP:

<capdash:viewStart/>

  <capdash:viewForm>

    ...

  </capdash:viewForm>

  <script>
	function select<portlet:namespace/>(id) {
          /* get the auto-generated HTML form */
	  var frm = $('<capdash:formId/>');
	  ...
          /* submit the form to the current page */
          submitFilterForm('<capdash:formId/>');
	}
  </script>

  ...

<capdash:viewEnd />

The <capdash:newPageId/> tag

This tag allows you to get the ID of the drill-down page set in the "apply to" section.

For example:

<capdash:viewStart/>

  <capdash:viewForm>

    ...

  </capdash:viewForm>

  <script>
	function select<portlet:namespace/>(id) {
          /* get the auto-generated HTML form */
	  var frm = $('<capdash:formId/>');
	  ...
          /* submit the form to the destination page */
          submitFilterFormChangingPage('<capdash:formId/>', '<capdash:newPageId/>');
	}
  </script>

  ...

<capdash:viewEnd />

The <capdash:messages/> tag

This tag, in conjunction with the PortletHelper.setMessage(MessageBean) method, allows you to display information to the user. You can use this tag in both view-mode and edit-mode JSPs.

For example, for a view-mode JSP:

<capdash:viewStart/>

  <capdash:messages />

  ...

<capdash:viewEnd />

Dashboard JavaScript methods

Various JavaScript methods are available for primary Dashboard functionalities. Here we list the most commonly used methods:

submitFilterForm(formid) method

This method saves the page parameter values for the current page by submitting the specified HTML form.

For example:

<capdash:viewStart/>

  <capdash:viewForm/>

  <script>
    ...
    /* submit the form to the current page */
    submitFilterForm('<capdash:formId/>');
  </script>
...
<capdash:viewEnd/>

submitFilterFormChangingPage(formid, pageid) method

This method saves the page parameter values for the destination page by submitting the specified HTML form.

For example:

<capdash:viewStart/>

  <capdash:viewForm/>

  <script>
    ...
    /* submit the form to the destination page */
    submitFilterFormChangingPage('<capdash:formId/>', '<capdash:newPageId/>');
  </script>
...
<capdash:viewEnd/>

submitSpecificFilter(pageId, paramName, paramValue) method

This method submits a specific user-portlet filter.

For example:

<script>
...
\* submit a specific user-portlet filter; notice the tag <portlet:namespace/>
appended to "caplan_filter_myfilter" to get a unique filter name
for the current portlet instance
*/
submitSpecificFilter(themeDisplay.getGroupId()+"/"+themeDisplay.getLayoutId(),
'caplan_filter_myfilter<portlet:namespace/>', myfilter_value);
</script>

refreshMe<portlet:namespace/>() method

This method reloads the current portlet.

Neptuny.parameters[paramName] method

This method returns the value of the page parameter for the current page.

For example:

<capdash:viewStart/>
  <script>
    /* get standard page parameters; for example, 
       for obtaining the System page parameter value: */
    var sysid = Neptuny.parameters['caplan_filter_sysid'];

    /* get custom page parameters; for example, */
    /* for obtaining the value of the custom parameter named "myparam": */
    var myparam = Neptuny.parameters['caplan_filter_custom_myparam']
  </script>
...
<capdash:viewEnd/>

Neptuny.refreshController.register(paramName, functionToInvoke) method

This method registers a user filter and selects the action to be taken upon its change. This function is typically used to register user-portlet filters.

For example:

<script>
  ...
  /* register a user-portlet filter; notice the tag <portlet:namespace/>
      appended to "caplan_filter_myfilter" to get a unique filter name
      for the current portlet instance
  */
  Neptuny.refreshController.register("caplan_filter_myfilter<portlet:namespace/>",
    refreshMe<portlet:namespace/>);
</script>

Neptuny.refreshController.unregister(paramName, functionToInvoke) method

This method unregisters a user-portlet filter.

For example:

<script>
  ...
  /* unregister a user-portlet filter; notice the tag <portlet:namespace/>
      appended to "caplan_filter_myfilter" to get a unique filter name
      for the current portlet instance
  */
  Neptuny.refreshController.unregister("caplan_filter_myfilter<portlet:namespace/>",
    refreshMe<portlet:namespace/>);
</script>