Package net.pricefx.server.dto.calculation

Class DashboardController

Object
AbstractPortletDto
DashboardController
All Implemented Interfaces:
Serializable, AppPages, Portlet, ComplexCalculationResult
public class DashboardController extends AbstractPortletDto implements Serializable, ComplexCalculationResult, AppPages
This class is used to generate the definition of a so-called controller dashboard portlet (or wizard). It consists generally of two types of elements: HTML text snippets, and buttons.
The buttons can trigger UI actions (e.g. opening a page) or backend actions (calling a backend URL). It's also possible to display plain HTML links instead of buttons, with the exact same functionality.

Create the controller with api.newController(), add the items, and return the controller from a logic element. The items are stacked on top of each other. A controller can be displayed in a dashboard and in most other places that show logic results, for example Quote line items, Custom Forms or Action Items, where it usually opens with the Show button.

The class implements AppPages, so the page constants are available on the controller, for example controller.QC_DETAILS_PAGE.

Example: 


 def controller = api.newController()
 controller.addHTML("<h2>Quotes</h2>")
 controller.addButton("Open Quotes", controller.QC_DETAILS_PAGE)
 return controller
See Also:

  • Constructor Details

    • DashboardController

      public DashboardController()
      Not intended for public use. Use api.newController() to create a controller.
      See Also:

  • Method Details

    • getResultType

      public String getResultType()
      Returns the result type of this calculation result.
      Specified by:
      getResultType in interface ComplexCalculationResult
      Returns:
      always "DASHBOARDCONTROLLER"

    • getItems

      public List<DashboardController.ControllerItem> getItems()
      Not intended for public use. Returns the items added to the controller. The server sends them to the user interface, which renders them.
      Returns:
      the items of the controller

    • addButton

      public void addButton(String label, String targetPage)
      Adds a button to the controller. When the user clicks the button, the target page opens.

      Example: 

      
 def controller = api.newController()
 controller.addButton("1. STEP: Go to Live Price Grids", controller.PB_LPG_PAGE)
      Parameters:
      label - The label of the button
      targetPage - The name of the target page. See predefined constants in AppPages interface.
      See Also:

    • addButton

      public void addButton(String label, String targetPage, Object targetPageState)
      Adds a button to the controller.

      Example: 

      
 def controller = api.newController()
 controller.addButton("2. STEP: Go to LPG ABC", controller.PB_LPG_PAGE, "45.PG")
      Parameters:
      label - The label of the button
      targetPage - The name of the target page. See predefined constants in AppPages interface.
      targetPageState - An extra parameter that is used for deep links. E.g. a typed id to open a specific page
      See Also:

    • addButton

      public void addButton(String label, String targetPage, Object targetPageState, Object componentId)
      Adds a button to the controller.

      Example: 

      
 def controller = api.newController()
 controller.addButton("Open Dashboard", controller.DB_DASHBOARDS_PAGE, null, "FirstDash")
      Parameters:
      label - The label of the button
      targetPage - The name of the target page. See predefined constants in AppPages interface.
      targetPageState - An extra parameter that is used for deep links. E.g. a typed id to open a specific page
      componentId - Some UI actions require a parameter in this field (e.g. opening a specific dashboard)
      See Also:

    • addLink

      public void addLink(String label, String targetPage)
      Adds a link (simple <A> tag) to the controller.

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

      Example: 

      
 def controller = api.newController()
 controller.addLink("1. STEP: Go to Live Price Grids", controller.PB_LPG_PAGE)
      Parameters:
      label - The label of the link
      targetPage - The name of the target page. See predefined constants in AppPages interface.
      Since:
      7.0 Bijou

    • addLink

      public void addLink(String label, String targetPage, Object targetPageState)
      Adds a link (simple <A> tag) to the controller.

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

      Example: 

      
 def controller = api.newController()
 controller.addLink("2. STEP: Go to LPG ABC", controller.PB_LPG_PAGE, "45.PG")
      Parameters:
      label - The label of the link
      targetPage - The name of the target page. See predefined constants in AppPages interface.
      targetPageState - An extra parameter that is used for deep links. E.g. a typed id to open a specific page
      Since:
      7.0 Bijou

    • addLink

      public void addLink(String label, String targetPage, Object targetPageState, Object componentId)
      Adds a link (simple <A> tag) to the controller.

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

      Example: 

      
 def controller = api.newController()
 controller.addLink("Open Dashboard", controller.DB_DASHBOARDS_PAGE, null, "FirstDash")
      Parameters:
      label - The label of the link
      targetPage - The name of the target page. See predefined constants in AppPages interface.
      targetPageState - An extra parameter that is used for deep links. E.g. a typed id to open a specific page
      componentId - Some UI actions require a parameter in this field (e.g. opening a specific dashboard)
      Since:
      7.0 Bijou

    • addBackendCall

      public void addBackendCall(String label, String apiUrl)
      Performs a backend call in the user's context (i.e. from the browser).

      The controller shows a button with the specified label. When the user clicks the button, the browser sends a POST request to the URL. The user gets no message about the result. To show one, use addBackendCall(String, String, String, String, String).

      Example: 

      
 def controller = api.newController()
 controller.addBackendCall("Calculate LPG", "/pricegridmanager.calculate/45")
      Parameters:
      label - The label of the button
      apiUrl - The URL to call
      See Also:

    • addBackendCall

      public void addBackendCall(String label, String apiUrl, String payload)
      Performs a backend call in the user's context (i.e. from the browser).

      The controller shows a button with the specified label. When the user clicks the button, the browser sends a POST request with the payload to the URL. The user gets no message about the result. To show one, use addBackendCall(String, String, String, String, String).

      Parameters:
      label - The label of the button
      apiUrl - The URL to call
      payload - The POST data to send along with the request, as a JSON string. If the value is not valid JSON, the request is not sent.
      See Also:

    • addBackendCall

      public void addBackendCall(String label, String apiUrl, String payload, String successMessage, String failMessage)
      Performs a backend call in the user's context (i.e. from the browser).

      The controller shows a button with the specified label. When the user clicks the button, the browser sends a POST request with the payload to the URL. Then it shows the success message or the fail message as a notification.

      Example: 

      
 def controller = api.newController()
 controller.addBackendCall("Calculate LPG", "/pricegridmanager.calculate/45", null, "OK", "Not OK")
      Parameters:
      label - The label of the button
      apiUrl - The URL to call
      payload - The POST data to send along with the request, as a JSON string. If the value is not valid JSON, the request is not sent and the fail message is shown.
      successMessage - A text that should be displayed in case of a successful response from the backend
      failMessage - A text that should be displayed in case of an error response from the backend
      See Also:

    • addHTML

      public void addHTML(String html)
      Adds an HTML snippet into the controller.

      Example: 

      
 def controller = api.newController()
 controller.addHTML("<h2>Welcome to Pricefx</h2>")

      HTML sanitization (since 17.0): HTML added to a dashboard is sanitized by default to prevent the execution of potentially malicious scripts (XSS). Only a restricted subset of tags and attributes is rendered and anything else is sanitized. In particular, raw <a> hyperlinks pointing to external URLs are displayed as HTML code (shown verbatim as text) instead of clickable links unless the URL targets pricefx.com/pricefx.eu or starts with #. Where a business case requires non-standard HTML or scripts, an administrator can disable sanitization for a specific partition via a feature flag, though using standard platform features (such as controller buttons) is recommended instead. See the Allowed HTML Tags and Attributes page in the Pricefx Knowledge Base for the full list of supported tags, attributes and URL schemes.

      Parameters:
      html - The html snippet.
      Since:
      11.1 - Paper Plane
      See Also:

    • addCollapsibleHTML

      public void addCollapsibleHTML(boolean isCollapsed, String sectionLabel, String html)
      Adds an HTML snippet into the controller as a collapsible section.

      In a dashboard, the collapsed or expanded state is saved when the user saves the dashboard preference. The saved state takes precedence over isCollapsed. It is stored by sectionLabel, so renaming the section discards it.

      Example: 

      
 def controller = api.newController()
 controller.addCollapsibleHTML(false, "section 1", "<h2>Welcome to Pricefx</h2>")

      HTML sanitization (since 17.0): HTML added to a dashboard is sanitized by default to prevent the execution of potentially malicious scripts (XSS). Only a restricted subset of tags and attributes is rendered and anything else is sanitized. In particular, raw <a> hyperlinks pointing to external URLs are displayed as HTML code (shown verbatim as text) instead of clickable links unless the URL targets pricefx.com/pricefx.eu or starts with #. Where a business case requires non-standard HTML or scripts, an administrator can disable sanitization for a specific partition via a feature flag, though using standard platform features (such as controller buttons) is recommended instead. See the Allowed HTML Tags and Attributes page in the Pricefx Knowledge Base for the full list of supported tags, attributes and URL schemes.

      Parameters:
      isCollapsed - Set to true to show the section collapsed when the controller is displayed.
      sectionLabel - label of the collapsible section
      html - The html snippet
      Since:
      11.1 - Paper Plane
      See Also:

    • addDownloadButton

      public void addDownloadButton(String label, String url)
      Adds a button that downloads a file, for example an Excel or PDF file. When the user clicks the button, the browser sends a POST request to the URL in the user's context and downloads the response as a file.

      When the URL runs a logic (/formulamanager.executeformula/<logic name>), URL parameters set the output format (output=xls or output=pdf) and the name of the file (fileName). Without fileName, an Excel file, or a PDF converted from it, is named after the logic plus a time stamp.

      Example: 

      
 def controller = api.newController()
 controller.addDownloadButton("Download Excel",
         "/formulamanager.executeformula/dashboard_export_logic?output=xls&fileName=MyDownloadedFile")
      Parameters:
      label - The label of the button
      url - The URL to call
      Since:
      3.4.3 - Cuba Libre
      See Also:

    • addDownloadButton

      public void addDownloadButton(String label, String url, String payload)
      Adds a button that downloads a file, for example an Excel or PDF file. When the user clicks the button, the browser sends a POST request with the payload to the URL in the user's context and downloads the response as a file.

      When the URL runs a logic (/formulamanager.executeformula/<logic name>), the payload supplies values for the parameters defined in the logic. The payload must be a JSON object. The logic reads the values with api.stringUserEntry(), for example api.stringUserEntry("region"). The targetDate key sets the target date of the logic instead. See addDownloadButton(String, String) for the URL parameters that set the output format and the file name.

      Example: 

      
 def controller = api.newController()
 controller.addDownloadButton("Download XLS", "/formulamanager.executeformula/DashboardExport?output=xls",
         '{"region": "EU"}')
      Parameters:
      label - The label of the button
      url - The URL to call
      payload - The POST data to send along with the request
      Since:
      3.4.3 - Cuba Libre
      See Also: