Package net.pricefx.common.apibuilder.chart

Class AbstractChartBuilder<C extends AbstractChartBuilder<C>>

Object
ObjectIdentity
AbstractBuilder
AbstractChartBuilder<C>
All Implemented Interfaces:
Portlet, Portlet
Direct Known Subclasses:
BarLineChart, BoxplotChart, BubbleChart, DataTableChart, DetailedTimeSeriesChart, HeatmapChart, HistogramChart, PieChart, ScatterChart, TimeSeriesChart, TimeSeriesScatterChart, WaterfallChart, WaterfallComparisonChart
public abstract class AbstractChartBuilder<C extends AbstractChartBuilder<C>> extends AbstractBuilder implements Portlet
Common base class for every chart definition builder returned by ChartBuilder, such as ScatterChart, TimeSeriesChart, and BarLineChart. You never instantiate this class or a concrete subclass of it directly; you get one by calling a factory method on ChartBuilder (itself obtained via api.newChartBuilder()), for example ChartBuilder.newScatter() or ChartBuilder.newBarLine().

Beyond the axis and series configuration each concrete chart type adds, this class provides the behavior every chart definition shares: sizing and positioning as a Dashboard portlet (withWidth(int), withHeight(int), withLayout(int, int) and their unit-aware overloads), informational, warning, and error messages, click-triggered Dashboard events (onRowClick(), onCellClick()), and populating the chart from a QueryBuilder Dashboard input (fromQueryBuilderState(java.util.Map)).

The chart definition a concrete subclass eventually builds is what Dashboard portlets, quote headers, and other Data Analyzer areas render. The same Groovy code is also what the View Expression function generates when a user builds the equivalent chart in the Pricefx UI.

See Also:

  • Field Details

    • layout

      protected Map<String,Object> layout

    • queryBuilderState

      protected Map<String,Object> queryBuilderState

    • messages

      protected Map<String,List<PortletMessage>> messages

    • dragDropEnabled

      protected boolean dragDropEnabled

    • resizingEnabled

      protected boolean resizingEnabled

  • Constructor Details

    • AbstractChartBuilder

      protected AbstractChartBuilder(String classId, IdGenerator idGenerator, Invocations<MethodInvocation> invocations)

  • Method Details

    • addInvocation

      protected String addInvocation(String methodName, Object... arguments)
      Overrides:
      addInvocation in class ObjectIdentity

    • getThis

      protected C getThis()

    • getDictionary

      public final Dictionary<C> getDictionary()
      Returns the builder for this chart's Dictionary, the Data Analyzer panel that controls formatting of dates, numbers, and other display labels (see the Dictionary option in the Data Analyzer UI). The Dictionary is built from a single opaque, pre-serialized string via Dictionary.buildFromOpaqueString(String), the same string the View Expression function generates when a user configures the Dictionary in the Pricefx UI; it is not meant to be hand-authored field by field.

      Example: 

      
 def chart = api.newChartBuilder().newScatter()
 chart.getDictionary().buildFromOpaqueString(dictionaryDefinition)
      Returns:
      this chart's Dictionary builder. Never null.
      See Also:

    • invokeGetOptions

      protected String invokeGetOptions()

    • getOptions

      public abstract AbstractChartOptions<C,?> getOptions()
      Returns this chart's Options builder. Each concrete chart type declares its own Options subclass (for example ScatterChart.ScatterOptions, BarLineChart.BarLineOptions) exposing the settings that apply to that chart type, such as title, subtitle, and axis label and bound overrides; the exact set of available options differs per chart type, which is why this method is declared abstract here rather than implemented once for every chart.
      Returns:
      this chart's type-specific AbstractChartOptions instance. Never null.

    • invokeAddSeries

      protected String invokeAddSeries()

    • invokeGetSeries

      protected String invokeGetSeries()

    • addAuxLine

      protected AuxLine<C> addAuxLine()

    • onRowClick

      public ChartEvents.OnRowClick<C> onRowClick()
      Configures a click-triggered event fired when a user clicks a row on this chart's Data tab (the grid view available for most Data Analyzer chart types), most commonly used with a DataTableChart. Call ChartEvents.OnRowClick.triggerEvent(String) on the returned builder, then ChartEvents.OnRowClick.RowClickTriggerEvent.withDimensionAsEventDataAttr(String) once per grid dimension whose value should be included in the event payload, or ChartEvents.OnRowClick.RowClickTriggerEvent.withAnyDimensionAsEventDataAttr() for all of them. The triggered event is typically consumed by an embedded Dashboard to refresh another portlet with the clicked row's data.

      Note: this event is not offered on the Data tab of a WaterfallChart or WaterfallComparisonChart.

      Example: 

      
 def table = api.newChartBuilder().newDataTable()
 table.onRowClick()
         .triggerEvent(api.dashboardWideEvent("productSelected"))
         .withDimensionAsEventDataAttr("ProductID")
      Returns:
      a new ChartEvents.OnRowClick builder for this chart. Never null.
      See Also:

    • onCellClick

      public ChartEvents.OnCellClick<C> onCellClick()
      Configures a click-triggered event fired when a user clicks a cell on this chart's Data tab (the grid view available for most Data Analyzer chart types), most commonly used with a DataTableChart. Call ChartEvents.OnCellClick.triggerEvent(String) on the returned builder, then ChartEvents.OnCellClick.CellClickTriggerEvent.withDimensionAsEventDataAttr(String) for the dimension(s) whose column the clicked cell must belong to (or ChartEvents.OnCellClick.CellClickTriggerEvent.withAnyDimensionAsEventDataAttr() for any column). Unlike onRowClick(), only the clicked cell's own value is included in the event payload, not the whole row. The triggered event is typically consumed by an embedded Dashboard to refresh another portlet with the clicked cell's data.

      Note: this event is not offered on the Data tab of a WaterfallChart or WaterfallComparisonChart.

      Example: 

      
 def table = api.newChartBuilder().newDataTable()
 table.onCellClick()
         .triggerEvent(api.dashboardWideEvent("cellSelected"))
         .withDimensionAsEventDataAttr("ProductID")
      Returns:
      a new ChartEvents.OnCellClick builder for this chart. Never null.
      See Also:

    • build

      protected ChartBuilderResult build(ChartType type)

    • withWidth

      public Portlet withWidth(int width, String unit)
      Description copied from interface: Portlet
      Builder style method for setting the width in supported units.

      Example – setting the width using the 12-column system (grid): 

      
 portlet.withWidth(12, "grid")
      Example – setting the width using pixels: 
      
 portlet.withWidth(400, "px") // == portlet.withWidth(400)
      Specified by:
      withWidth in interface Portlet
      Parameters:
      width - Specifies the width of the portlet (in unit).
      unit - Specifies the unit of the width (grid, px). If the unit is not specified then px is used as default.
      Returns:
      The current portlet object of the specified size.
      See Also:

    • withHeight

      public Portlet withHeight(int height, String unit)
      Description copied from interface: Portlet
      Builder style method for setting the height in supported units.

      Example – setting the height using the 12-column system (grid): 

      
 portlet.withHeight(12, "grid")
      Example – setting the height using pixels: 
      
 portlet.withHeight(800, "px") // == portlet.withHeight(800)
      Specified by:
      withHeight in interface Portlet
      Parameters:
      height - Specifies the height of the portlet (in unit).
      unit - Specifies the unit of the height (grid, px). If the unit is not specified then px is used as default.
      Returns:
      The current portlet object of the specified size.
      See Also:

    • withLayout

      public Portlet withLayout(int width, int height, String unit)
      Description copied from interface: Portlet
      Builder style method for setting width and height in specified units.

      Example - sets the portlet size to the specified grid size: 

      
 def matrix = api.newMatrix("column1", "column2", "column3")
      matrix.addRow(1, "a", "f")
      matrix.addRow(2, "b", "g")
      matrix.withLayout(3, 3, "grid")

 return matrix
      Specified by:
      withLayout in interface Portlet
      Parameters:
      width - Specifies the width of the portlet.
      height - Specifies the height of the portlet.
      unit - Specifies a unit of the layout (grid, px).
      Returns:
      The current portlet object of the specified size.
      See Also:

    • withInfo

      public Portlet withInfo(String code, String userMsg, String techMsg)
      Description copied from interface: Portlet
      Adds an info message to the given portlet. One portlet can have multiple messages. It is a different concept than yellow/red alerts.

      Example: 

      
 portlet.withInfo("101", "Chart data may be outdated", "Bubble Chart data is outdated, because of ...")
      Specified by:
      withInfo in interface Portlet
      Parameters:
      code - Info code allows pinpointing the place of the related issue in code.
      userMsg - Info message is displayed to a user in UI.
      techMsg - Technical message is hidden by default, only for the investigation purposes.

    • withWarning

      public Portlet withWarning(String code, String userMsg, String techMsg)
      Description copied from interface: Portlet
      Adds a warning message to the given portlet. One portlet can have multiple messages. It is a different concept than yellow/red alerts.

      Example: 

      
 portlet.withWarning("102", "Chart data is missing", "Bubble Chart data is missing, because of ...")
      Specified by:
      withWarning in interface Portlet
      Parameters:
      code - Warning code allows pinpointing the place where the warning is thrown in code.
      userMsg - A warning message is displayed to a user in UI.
      techMsg - Technical message is hidden by default, only for the investigation purposes.

    • withError

      public Portlet withError(String code, String userMsg, String techMsg)
      Description copied from interface: Portlet
      Adds an error message to the given portlet. One portlet can have multiple messages. It is a different concept than yellow/red alerts.

      Example: 

      
 portlet.withError("103", "Chart was not found", "Bubble Chart could not be found, because of ...")
      Specified by:
      withError in interface Portlet
      Parameters:
      code - Error code allows pinpointing the place where the error is thrown in code.
      userMsg - Error message is displayed to a user in UI.
      techMsg - Technical message is hidden by default, only for the investigation purposes.

    • withLayout

      public Portlet withLayout(int width, int height, String wUnit, String hUnit)
      Builder style method for setting width and height in independently specified units, for when the width and height need different units, for example a fixed pixel height with a grid-relative width. This is an extension beyond Portlet.withLayout(int, int, String), which requires the same unit for both dimensions.

      Note: unlike the single-unit overload, this method does not validate width/height against the 1-12 grid bounds (see Portlet.UNIT_GRID); only the unit tokens themselves are validated.

      Example: 

      
 chart.withLayout(6, 400, "grid", "px")
      Parameters:
      width - Specifies the width of the portlet (in wUnit).
      height - Specifies the height of the portlet (in hUnit).
      wUnit - Specifies the unit of the width (grid, px).
      hUnit - Specifies the unit of the height (grid, px).
      Returns:
      this portlet instance, sized as specified
      Throws:
      RuntimeException - if wUnit or hUnit is not one of the supported units
      See Also:

    • value

      protected Map<String,Object> value(int value, String unit)

    • withWidth

      public Portlet withWidth(int width)
      Description copied from interface: Portlet
      Builder style method for setting the width in pixels.
      Specified by:
      withWidth in interface Portlet
      Parameters:
      width - specify the width of the portlet (in pixels)
      Returns:
      The current portlet object of the specified size.
      See Also:

    • withHeight

      public Portlet withHeight(int height)
      Description copied from interface: Portlet
      Builder style method for setting the height in pixels.
      Specified by:
      withHeight in interface Portlet
      Parameters:
      height - specify the height of the portlet (in pixels)
      Returns:
      The current portlet object of the specified size.
      See Also:

    • withLayout

      public Portlet withLayout(int width, int height)
      Description copied from interface: Portlet
      Builder style method for setting width and height in pixels.
      Specified by:
      withLayout in interface Portlet
      Parameters:
      width - specify the width of the portlet (in pixels)
      height - specify the height of the portlet (in pixels)
      Returns:
      The current portlet object of the specified size.
      See Also:

    • layout

      protected Map<String,Object> layout()

    • fromQueryBuilderState

      public C fromQueryBuilderState(Map<String,Object> state)
      Configures a DataTableChart based on the output of the QueryBuilder Dashboard input.
      Note: So far the only supported chart type is DataTable, which will show a separate tab for each series configured in the QueryBuilder input.

      Example: 

      
 def qbState = input.MyQueryBuilder
 api.newChartBuilder()
     .newDataTable()
     .fromQueryBuilderState(qbState)
     .build()
      Parameters:
      state - Properties Map as returned by the QueryBuilder input
      Returns:
      self
      Since:
      11.0 Paper Plane for DataTableChart, 12.0 Clover Club experimental for all other chart types

    • withDragDrop

      public Portlet withDragDrop(boolean enabled)
      Description copied from interface: Portlet
      Enables or disables the drag&drop feature for portlets. Set to false to disable the drag&drop option. The default state is ENABLED.

      Example - disables the drag&drop of the Result Matrix portlet: 

      
 def matrix = api.newMatrix("column1", "column2", "column3")
      matrix.addRow(1, "a", "f")
      matrix.addRow(2, "b", "g")
      matrix.withDragDrop(false)

 return matrix
      Specified by:
      withDragDrop in interface Portlet
      Parameters:
      enabled - on/off switch. Default = true.
      Returns:
      this Portlet instance

    • withResizing

      public Portlet withResizing(boolean enabled)
      Description copied from interface: Portlet
      Enables or disables the resizing feature for portlets. Set to false to disable the resizing of the portlet. The default state is ENABLED.

      Example - disables the resizing option of the Result Matrix portlet: 

      
 def matrix = api.newMatrix("column1", "column2", "column3")
      matrix.addRow(1, "a", "f")
      matrix.addRow(2, "b", "g")
      matrix.withResizing(false)

 return matrix
      Specified by:
      withResizing in interface Portlet
      Parameters:
      enabled - on/off switch. Default = true.
      Returns:
      this Portlet instance

    • withTab

      public Portlet withTab(String tabName)
      Description copied from interface: Portlet
      Assigns the portlet to a specific tab in a multitab dashboard.

      Tabs must be defined in the Model Class (MC) definition under the dashboardTabs list for the corresponding step.
      If the tab name is not found in the MC definition, the portlet falls back to the default tab and a warning is logged to the console.

      Example: 

      
     return api.inputBuilderFactory().createInputMatrix("MatrixEntry")
             .setColumns(columns)
             .setColumnValueOptions(columnsValueOptions)
             .setValue([
                 [col1: "a1", col2: "b1"],
                 [col1: "a2", col2: "b2"]
             ])
             .setLabel("MatrixEntry")
             .setTab("multitab_dashboard_inputs_and_portlets")
             .getInput()
      Specified by:
      withTab in interface Portlet
      Parameters:
      tabName - Name of the tab as defined in dashboardTabs in the Model Class JSON
      Returns:
      the current portlet instance
      See Also:

    • withLabelOverride

      public Portlet withLabelOverride(String label)
      Description copied from interface: Portlet
      Overrides the default label of a portlet. This method is implemented for the subtypes of AbstractPortletDto and AbstractChartBuilder only.
      Specified by:
      withLabelOverride in interface Portlet
      Parameters:
      label - Suggested new label
      Returns:
      the current portlet instance