Interface DashboardApi

All Superinterfaces:
Portlet

public interface DashboardApi extends Portlet
DashboardApi interface is used for configuration of Embedded Dashboards.

With a few lines of Groovy code, it is very easy to embed a dashboard as a portlet of another dashboard. This creates an interactive dashboard which can change dynamically in reaction to an event. Clicking on a result in one portlet triggers an event, which changes the input (and therefore the content) of another, embedded portlet. For example, you have a dashboard with a grid, which contains details about products, and a chart that graphically displays the product data. When you select a row in the grid (a particular product), you want to see the chart automatically updated so that it displays the correct data for the selected product.

Dashboard Display Modes

There are three ways to display the dashboard:

  • Embedded – The dashboard is embedded in the master dashboard as another portlet/dashlet.
  • Tab – The dashboard is opened in a new tab.
  • Window – The dashboard is opened in a new popup window.

The new tab or window is opened only once (i.e. on the first event) and is then reused/recalculated on every subsequent event. Both the tab and window can be closed automatically on a specified event. Use the option andCloseOn(String).

Examples

See Also:
  • Method Details

    • setParam

      DashboardApi setParam(String paramName, Object value)

      The main dashboard can provide input parameters to the embedded dashboard via

      
       DashboardApi.setParam(String param_name, Object param_value)
       

      The embedded dashboard can then read the parameters via input.param_name

      Parameters:
      paramName - name of the parameter
      value - value of the parameter
      Returns:
      DashboardApi
      See Also:
    • setParams

      DashboardApi setParams(Map<String,Object> nameValueMap)
      Convenience method to set a number of parameters at once. It is equivalent to repeatedly calling dashboardApi.setParam() as previously set parameters will not be cleared.
      Parameters:
      nameValueMap - parameter values mapped by parameter name
      Returns:
      DashboardApi
      Since:
      11.3
      See Also:
    • setPortlet

      DashboardApi setPortlet(String portletName)
      Instead of embedding a whole dashboard, only the one requested portlet will be displayed.
      Parameters:
      portletName - name of the portlet to display (same as the element name of the dashboard's logic)
      Returns:
      DashboardApi
      Since:
      11.3
    • showEmbedded

      DashboardApi showEmbedded()
      Shows given dashboard as an embedded dashboard of another (main) dashboard.

      Example:

      
           return api.dashboard('fooDashboardName')
                     // Here the user can assign values to the embedded dashboard inputs
                     .setParam('Customer Id', 'CD-00067')
                     // ... and of course this means it could also "forward" its own inputs
                     .setParam('Product Id', input.'Product Id')
                     // Show the dashboard embedded ...
                     .showEmbedded()
       
      Returns:
      DashboardApi
    • andRecalculateOn

      DashboardApi andRecalculateOn(String eventName)

      Specifies on what event the embedded dashboard will be recalculated. Event name created using call PublicGroovyAPI.dashboardWideEvent(String)

      Example:

      
           def eventName = api.dashboardWideEvent('event_name')
      
           return api.dashboard('fooDashboardName')
                     // Here the user can assign values to the embedded dashboard inputs
                    .setParam('Customer Id', 'CD-00067')
                    // ... and of course this means it could also "forward" its own inputs
                    .setParam('Product Id', input.'Product Id')
                    // Show the dashboard embedded ...
                    .showEmbedded()
                    .andRecalculateOn(eventName)
       
      Parameters:
      eventName - parameter name created using PublicGroovyAPI.dashboardWideEvent(String)
      Returns:
      DashboardApi
      See Also:
    • openInTabOrRecalculateOn

      DashboardApi openInTabOrRecalculateOn(String eventName)

      On specified event the embedded dashboard will be opened in a new tab and recalculated. Event name created using call PublicGroovyAPI.dashboardWideEvent(String)

      Example:

      
           def eventName = api.dashboardWideEvent('event_name')
      
           return api.dashboard('fooDashboardName')
                     // Here the user can assign values to the embedded dashboard inputs
                     .setParam('Customer Id', 'CD-00067')
                     // ... and of course this means it could also "forward" its own inputs
                    .setParam('Product Id', input.'Product Id')
                    .openInTabOrRecalculateOn(eventName)
       
      Parameters:
      eventName - name of the event, created using PublicGroovyAPI.dashboardWideEvent(String)
      Returns:
      DashboardApi
      See Also:
    • openInWindowOrRecalculateOn

      @Deprecated DashboardApi openInWindowOrRecalculateOn(String eventName)
      Deprecated.
      Deprecated use openInModalOrRecalculateOn(java.lang.String) instead

      On specified event the embedded dashboard will be opened in a new modal window and recalculated. Event name is created using call PublicGroovyAPI.dashboardWideEvent(String)

      Example:

      
           def eventName = api.dashboardWideEvent('event_name')
      
           return api.dashboard('fooDashboardName')
                     // Here the user can assign values to the embedded dashboard inputs
                     .setParam('Customer Id', 'CD-00067')
                     // ... and of course this means it could also "forward" its own inputs
                     .setParam('Product Id', input.'Product Id')
                     // Show the dashboard embedded ...
                     .openInWindowTabOrRecalculateOn(eventName)
       
      Parameters:
      eventName - name of the event, created using PublicGroovyAPI.dashboardWideEvent(String)
      Returns:
      DashboardApi
      See Also:
    • openInModalOrRecalculateOn

      DashboardApi openInModalOrRecalculateOn(String eventName)

      On specified event the embedded dashboard will be opened in a new modal window and recalculated. Event name is created using call PublicGroovyAPI.dashboardWideEvent(String)

      Example:

      
           def eventName = api.dashboardWideEvent('event_name')
      
           return api.dashboard('fooDashboardName')
                     // Here the user can assign values to the embedded dashboard inputs
                     .setParam('Customer Id', 'CD-00067')
                     // ... and of course this means it could also "forward" its own inputs
                     .setParam('Product Id', input.'Product Id')
                     // Show the dashboard embedded ...
                    .openInModalOrRecalculateOn(eventName)
       
      Parameters:
      eventName - name of the event, created using PublicGroovyAPI.dashboardWideEvent(String)
      Returns:
      DashboardApi
    • andCloseOn

      DashboardApi andCloseOn(String eventName)
      Closes a tab or popup window when the specified event is triggered. Note:Not allowed if embedded as a portlet using showEmbedded().
      Parameters:
      eventName - name of the event, created using PublicGroovyAPI.dashboardWideEvent(String)
      Returns:
      DashboardApi
      Throws:
      IllegalStateException - when used with embedded dashboard
      See Also:
    • withEventDataAttr

      DashboardApi withEventDataAttr(String attrName)

      Allows to expose event payload - attribute of the specified name - as a parameter that can be read in the embedded dashboard. This method is used together with @link asParam(String).

      
                      def eventName = api.dashboardWideEvent('rowClick')
      
                      return api.dashboard('embeddedDashboardName').showEmbedded()
                      .andRecalculateOn('rowClick')
                      // expose the event payload
                      .withEventDataAttr('attributeName1').asParam('paramName1')
                      .withEventDataAttr('attributeName2').asParam('paramName2')
       
      Parameters:
      attrName - name of the attribute
      Returns:
      DashboardApi
      See Also:
    • asParam

      DashboardApi asParam(String paramName)
      Exposes event payload - attribute of the specified name - as a parameter that can be read in the embedded dashboard. The embedded dashboard's logic can read the parameter value as using PublicGroovyAPI.input(String).
      
       def eventName = api.dashboardWideEvent('rowClick')
      
       return api.dashboard('embeddedDashboardName').showEmbedded()
                 .andRecalculateOn('rowClick')
                 // expose the event payload
                 .withEventDataAttr('attributeName1').asParam('paramName1')
                 .withEventDataAttr('attributeName2').asParam('paramName2')
       
      Parameters:
      paramName - name of the parameter
      Returns:
      DashboardApi
      See Also:
    • withInputsHidden

      DashboardApi withInputsHidden(boolean hidden)

      Optionally hides all embedded Dashboard input parameters from the Unity UI's inputs panel.

      Note: This is available for the Unity UI only. No backporting planned for the Classic UI.

      Parameters:
      hidden -
      Returns:
      DashboardApi
      Since:
      8.0 Godfather
    • withInputsHidden

      default DashboardApi withInputsHidden()

      Optionally hides all embedded Dashboard input parameters from the Unity UI's inputs panel.

      Convenience method acting like withInputsHidden(true).

      Note: This is available for the Unity UI only. No backporting planned for the Classic UI.

      Returns:
      DashboardApi
      Since:
      8.0 Godfather
    • withEmbeddedIconHidden

      DashboardApi withEmbeddedIconHidden()
      Hides the icon which notifies users that a portlet is part of an embedded Dashboard.
      Returns:
      DashboardApi
      Since:
      11.0 Paper Plane
    • withPreferences

      DashboardApi withPreferences(Map<String,Object> prefs)
      Hides the preferences menu and use the provided properties map instead of loading any saved preferences.
      Returns:
      DashboardApi
      Since:
      11.0 Paper Plane
    • newExecution

      DashboardExecution newExecution()
      Create execution to run a dashboard logic.
      
       api.dashboard(dashboardName).newExecution()
       
      Returns:
      DashboardExecution
      Since:
      12.0 Clover Club