Package com.jbstrap.ui.components.sparkline

Class Sparkline

java.lang.Object
com.jbstrap.core.messagebus.MessageBus
com.jbstrap.ui.Component<Sparkline>
com.jbstrap.ui.components.sparkline.Sparkline
All Implemented Interfaces:
Animatable<Sparkline>, CanDrop<Sparkline>, Clickable<Sparkline>, Draggable<Sparkline>, Fetchable<Sparkline>, HandleMouseEvents<Sparkline>, BasedOnDataDescriptor<Sparkline>, Touchable<Sparkline>
public class Sparkline extends Component<Sparkline> implements Fetchable<Sparkline>, Animatable<Sparkline>, Clickable<Sparkline>, HandleMouseEvents<Sparkline>, Touchable<Sparkline>, CanDrop<Sparkline>, Draggable<Sparkline>, BasedOnDataDescriptor<Sparkline>

Sparkline component

The sparkline component is a simplified chart component. Use the sparkline component to visualize numeric data on a chart. These charts can later be reused as a list grid column or dashboard panel.

The component is not intended to visualize complex or large-scale charts and has a limited range of settings. The component’s main purpose is to to provide an overview of a large amount of data or to visualize trends.

Supported events:

AnimationStart AnimationEnd, Click, DoubleClick, MouseDown, MouseDown, MouseLeave, MouseMove, MouseOver, MouseOut, MouseUp, Wheel, TouchCancel, TouchEnd, TouchMove, TouchStart, Drop, DragStart, DragEnd

Since:
4.0
Author:
JBStrap

  • Constructor Details

    • Sparkline

      public Sparkline()
      Creates a simple line chart.

    • Sparkline

      public Sparkline(String language)
      Creates a simple line chart according to the specified language code.
      Parameters:
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.

    • Sparkline

      public Sparkline(String id, String language)
      Creates a simple line chart according to the specified language code.
      Parameters:
      id - The component ID. The ID specified here will appear in the HTML tag as an ID attribute. If there are multiple components displayed, that have the same ID, the ID numbers will be numbered, in the order they are displayed. (For example, if the ID is 'COMPONENT' then it will be numbered like this: COMPONENT, COMPONENT_1, COMPONENT_2 etc.)
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.

    • Sparkline

      public Sparkline(SparklineType type)
      Creates a chart with the specified type.
      Parameters:
      type - Chart type Available chart types are listed in the enum SparklineType. If null is specified, the default chart type SparklineType.LINE_CHART is used to create the chart.

    • Sparkline

      public Sparkline(String language, SparklineType type)
      Creates a chart with the specified type according to the language code.
      Parameters:
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      type - Chart type * Available chart types are listed in the enum SparklineType. If null is specified, the default chart type is used to create SparklineType.LINE_CHART.

    • Sparkline

      public Sparkline(List<Number> values)
      Creates a simple line chart based on the specified data.
      Parameters:
      values - A list containing the numeric values to be displayed If null is specified, the chart will not be displayed.

    • Sparkline

      public Sparkline(String language, List<Number> values)
      Creates a simple line chart based on the specified data according to the language code.
      Parameters:
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      values - A list containing numeric values to be displayed If null is specified, the chart will not be displayed.

    • Sparkline

      public Sparkline(SparklineType type, List<Number> value)
      Creates a chart with the specified type and data
      Parameters:
      type - Chart type * Available chart types are listed in the enum SparklineType. If null is specified, the default chart type is used to create SparklineType.LINE_CHART.
      value - A list containing the numeric values to be displayed If null is specified, the chart will not be displayed.

    • Sparkline

      public Sparkline(String language, SparklineType type, List<Number> value)
      Creates a chart with the specified type and data according to the language code.
      Parameters:
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      type - Chart type * Available chart types are listed in the enum SparklineType. If null is specified, the default chart type is used to create SparklineType.LINE_CHART.
      value - A list containing the numeric values to be displayed If null is specified, the chart will not be displayed.

    • Sparkline

      public Sparkline(String id, String language, SparklineType type, List<Number> value)
      Creates a chart with the specified type and data according to the language code.
      Parameters:
      id - The component ID. The ID specified here will appear in the HTML tag as an ID attribute. If there are multiple components displayed, that have the same ID, the ID numbers will be numbered, in the order they are displayed. (For example, if the ID is 'COMPONENT' then it will be numbered like this: COMPONENT, COMPONENT_1, COMPONENT_2 etc.)
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      type - Chart type * Available chart types are listed in the enum SparklineType. If null is specified, the default chart type is used to create SparklineType.LINE_CHART.
      value - A list containing the numeric values to be displayed If null is specified, the chart will not be displayed.

    • Sparkline

      public Sparkline(DataDescriptorColumn dsColumn)

      Creates a chart based on the specified DataDescriptor column.

      The method creates and sets the chart based on the specified DataDescriptor column. The component uses the following DataDescriptor column parameters:

      • MetaParamName.DATADESCRIPTOR - This parameter specifies the sparkline component’s DataDescriptor
      • MetaParamName.DATA_COLUMN - This parameter specifies the DataDescriptor column Sparkline charts display only numeric data and the column specified here must contain numeric data.
      • MetaParamName.CHART_TYPE - This parameter specifies the chart type. Specify a value of the SparklineType enum in text format. That is, enter “PIE_CHART” for a pie chart. If the parameter is not specified or you enter a text which has no equivalent in the SparklineType enum, a line chart is displayed.
      • MetaParamName.WIDTH - This parameter specifies chart width. Width is specified using the CSS3 standard.
      • MetaParamName.ID_FIELD_NAME - This parameter specifies a DataDescriptor column name with the data set ID. The ID specified here must be the ID of the data set to be displayed.
      • MetaParamName.CRITERIA - This parameter specifies the filter criterion for sparkline data queries.
      • MetaParamName.ORDER - This parameter specifies columns separated with commas (“,”) used to order the queried data. If you place a “-” sign before a column name, it inverts the column sort order.

      Parameters:
      dsColumn - DataDescriptor column instance used to create the chart
      Throws:
      NullPointerException - Thrown if the specified column is set to null or there is no DATADESCRIPTOR parameter in the column or the DataDescriptor specified in the DATADESCRIPTOR parameter does not exist.

    • Sparkline

      public Sparkline(DataDescriptorColumn dsColumn, String language)

      Creates a chart based on the specified DataDescriptor column according to the language code.

      The method creates and sets the chart based on the DataDescriptor column. The component uses the following DataDescriptor column parameters:

      • MetaParamName.DATADESCRIPTOR - This parameter specifies the sparkline component’s DataDescriptor
      • MetaParamName.DATA_COLUMN - This parameter specifies the DataDescriptor column A sparkline chart only displays numeric data and the column specified here must also contain numeric data.
      • MetaParamName.CHART_TYPE - This parameter specifies the chart type. Specify a value of the SparklineType enum in text format. That is, enter “PIE_CHART” for a pie chart. If the parameter is not specified or you enter a text which has no equivalent in the SparklineType enum, a line chart is displayed.
      • MetaParamName.WIDTH - This parameter specifies chart width. Width is specified using the CSS3 standard.
      • MetaParamName.ID_FIELD_NAME - This parameter specifies a DataDescriptor column name with the data set ID. The ID specified here must be the ID of the data set to be displayed.
      • MetaParamName.CRITERIA - This parameter specifies the filter criterion for sparkline data queries.
      • MetaParamName.ORDER - This parameter specifies columns separated with commas (“,”) used to order the queried data. If you place a “-” sign before a column name, it inverts the column sort order.

      Parameters:
      dsColumn - DataDescriptor column instance used to create the chart
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      Throws:
      NullPointerException - Thrown if the specified column is set to null or there is no DATADESCRIPTOR parameter in the column or the DataDescriptor specified in the DATADESCRIPTOR parameter does not exist.

  • Method Details

    • addComponent

      public Sparkline addComponent(Component<?> component)
      Adds another sparkline component to the current one.
      Overrides:
      addComponent in class Component<Sparkline>
      Parameters:
      component - Sparkline component to be added
      Returns:
      Sparkline component
      Throws:
      UnsupportedOperationException - Thrown if the specified component is not a sparkline component or if the current component already contains one or more sparklines

    • addComponents

      public Sparkline addComponents(Component<?>... components)
      Adds multiple sparkline components to the current one.
      Overrides:
      addComponents in class Component<Sparkline>
      Parameters:
      components - An enumeration of sparkline components to be added
      Returns:
      Sparkline component
      Throws:
      UnsupportedOperationException - Thrown if one of the specified components is not a sparkline component or if the current component already contains one or more sparklines

    • removeComponent

      public Sparkline removeComponent(Component<?> component)
      Removes a sparkline component from the current one.
      Overrides:
      removeComponent in class Component<Sparkline>
      Parameters:
      component - Sparkline component to be removed
      Returns:
      Sparkline component
      Throws:
      UnsupportedOperationException - Thrown if the specified component is not a sparkline component

    • removeComponents

      public Sparkline removeComponents(Component<?>... components)
      Removes multiple sparkline components from the current one.
      Overrides:
      removeComponents in class Component<Sparkline>
      Parameters:
      components - An enumeration of all sparkline components to be removed
      Returns:
      Sparkline component
      Throws:
      UnsupportedOperationException - Thrown if one of the specified components is not a sparkline component

    • writeHTML

      public boolean writeHTML(StringWriter writer)
      Description copied from class: Component
      Creates the component's HTML equivalent

      This method doesn't need to be used during application development. This method is used when developing a custom component. When creating a custom component, this method needs to be implemented. In the parameter (StringWriter class) the component's HTML equivalent must be specified, and the method has to return with a Boolean value. This boolean value determines if the component was drawn. If the user doesn't have access right to the component, or if the component couldn't be drawn, it should return with false. Otherwise, it must return with true.

      Specified by:
      writeHTML in class Component<Sparkline>
      Returns:
      If the componentwas drawn, true, otherwise false

    • init

      public void init() throws JavaScriptLoadError
      Description copied from class: Component
      The component initialization method.

      Empty method, only needs to be overwritten when making a custom component, that needs to call an initializing JavaScript on the client side. The method is called by the framework after the component is drawn, but before the afterDraw() method. The use of this method during application development is not allowed. This method is meant for inner use only.

      Overrides:
      init in class Component<Sparkline>
      Throws:
      JavaScriptLoadError - If there was a JavaScript error during the initialization.

    • onShow

      public void onShow()
      Description copied from class: Component
      The operations to be executed after the component is displayed on the client

      By default, this is an empty method. It has to be overwritten on a component or page, if additional operations have to be executed after the component is displayed. This method is nearly identical to the afterDraw() method, they differ in when they are executed. This method runs after the component is displayed on the client. Meaning that it is executed even if the component isn't redrawn, but only set to be visible after being hidden.

      Overrides:
      onShow in class Component<Sparkline>

    • redraw

      public Sparkline redraw()
      Redraws the component on the interface.
      Overrides:
      redraw in class Component<Sparkline>
      Returns:
      The component

    • setSourceId

      public Sparkline setSourceId(Object sourceId)
      Sets the data column name. The DataDescriptor column identifies the data set to be displayed.
      Parameters:
      sourceId - DataDescriptor column name
      Returns:
      Sparkline component

    • getSourceId

      public Object getSourceId()
      Sets the data column name. The DataDescriptor column identifies the data set to be displayed.
      Returns:
      The name of the DataDescriptor containing displayed values or null if not set

    • fetchData

      public Sparkline fetchData()
      Queries data from the database.
      Specified by:
      fetchData in interface Fetchable<Sparkline>
      Returns:
      The component
      Throws:
      IllegalArgumentException - Thrown if there is no DataDescriptor set for the component or there is a DataDescriptor, but the column with the displayed values is not specified or the data set ID is not specified

    • clearValue

      public Sparkline clearValue()
      Deletes sparkline component values.
      Returns:
      Sparkline component

    • getType

      public SparklineType getType()
      Gets the displayed chart type.
      Returns:
      Chart type

    • setType

      public Sparkline setType(SparklineType type)
      Sets displayed chart type.
      Parameters:
      type - Chart type Available chart types are listed in the enum SparklineType. If null is set, the default SparklineType.LINE_CHART is used.
      Returns:
      Sparkline component

    • getValue

      public List<Number> getValue()
      Gets the displayed values.
      Returns:
      A list of displayed numeric values If the component does not contain any values, an empty list is returned.

    • setValue

      public Sparkline setValue(List<Number> value)
      Sets the component’s displayed values. The values specified here overwrite previous values.
      Parameters:
      value - A list of numeric values If null is specified, the chart will not be displayed.
      Returns:
      Sparkline component

    • getWidth

      public String getWidth()
      Gets the component’s width.
      Returns:
      The current width of the component as entered or the default width

    • setWidth

      public Sparkline setWidth(Integer width)
      Sets the component width.
      Parameters:
      width - Width in pixels If null is set, the method does nothing.
      Returns:
      Sparkline component
      Throws:
      UnsupportedOperationException - Thrown if the displayed chart type is SparklineType.DISCRETE_CHART

    • setWidth

      public Sparkline setWidth(String width)
      Sets the component width.
      Parameters:
      width - Component width as defined in CSS3 If null is set, the method does nothing.
      Returns:
      Sparkline component
      Throws:
      UnsupportedOperationException - Thrown if the displayed chart type is SparklineType.DISCRETE_CHART

    • getHeight

      public String getHeight()
      Gets the component height.
      Returns:
      Component height as entered or null if no component height is specified

    • setHeight

      public Sparkline setHeight(Integer height)
      Sets component height.
      Parameters:
      height - Component height in pixels If null is set, the method does nothing.
      Returns:
      Sparkline component

    • setHeight

      public Sparkline setHeight(String height)
      Sets component height.
      Parameters:
      height - The height value of the component as defined in CSS3 If null is set, the method does nothing.
      Returns:
      Sparkline component

    • getChartRangeMin

      public Integer getChartRangeMin()
      Gets the chart’s minimum value.
      Returns:
      The chart’s minimum value or null if not set

    • setChartRangeMin

      public Sparkline setChartRangeMin(Integer chartRangeMin)
      Sets the minimum value for the chart.
      Parameters:
      chartRangeMin - Minimum value for the chart If null is set, the minimum value is deleted.
      Returns:
      Sparkline component

    • getChartRangeMax

      public Integer getChartRangeMax()
      Gets the chart’s maximum value.
      Returns:
      The chart’s maximum value or null if not set

    • setChartRangeMax

      public Sparkline setChartRangeMax(Integer chartRangeMax)
      Sets the maximum value for the chart.
      Parameters:
      chartRangeMax - Maximum value for the chart If null is set, the method does nothing.
      Returns:
      Sparkline component

    • getColor

      public String getColor()
      Gets chart color.
      Returns:
      Chart color or null if no chart color is specified

    • setColor

      public Sparkline setColor(String color)
      Sets chart color.
      Parameters:
      color - Chart color as defined in the CSS3 standard If null is set, the chart color is deleted.
      Returns:
      Sparkline component

    • getNegativeColor

      public String getNegativeColor()
      Gets the color of the negative values on the chart.
      Returns:
      The color of the negative values on the chart or null if not specified

    • setNegativeColor

      public Sparkline setNegativeColor(String negativeColor)
      Sets the color of the negative values on the chart.
      Parameters:
      negativeColor - The color of the negative values on the chart as defined in the CSS3 standard * If null is set, the color is deleted.
      Returns:
      Sparkline component

    • getDataDescriptor

      public DataDescriptor getDataDescriptor()
      Gets the sparkline DataDescriptor.
      Specified by:
      getDataDescriptor in interface BasedOnDataDescriptor<Sparkline>
      Returns:
      DataDescriptor used by the sparkline or null if no DataDescriptor is specified

    • setDataDescriptor

      public Sparkline setDataDescriptor(DataDescriptor dataDescriptor)
      Sets the sparkline DataDescriptor.
      Specified by:
      setDataDescriptor in interface BasedOnDataDescriptor<Sparkline>
      Parameters:
      dataDescriptor - DataDescriptor instance used by the component If null is set, the DataDescriptor associated with the component is deleted and the component is unable to read data from it.
      Returns:
      Sparkline component

    • getDataColumn

      public String getDataColumn()
      Gets the column name containing the displayed values.
      Returns:
      The name of the DataDescriptor column containing displayed values or null if not set

    • setDataColumn

      public Sparkline setDataColumn(String dataColumn)
      Sets the data column name. The DataDescriptor column identifies the data set to be displayed.
      Parameters:
      dataColumn - DataDescriptor column name
      Returns:
      Sparkline component

    • getFilterCriteria

      public Criteria getFilterCriteria()
      Gets the filter criterion used for the query.
      Returns:
      Filter criterion used for the query or null if no filter criterion is specified

    • setFilterCriteria

      public Sparkline setFilterCriteria(Criteria criteria)
      Sets the filter criterion used during data query.
      Parameters:
      criteria - Filter criterion used for data query If null is set, no filter criterion is used for data query.
      Returns:
      Sparkline component

    • getTooltipPrefix

      public String getTooltipPrefix()
      Gets the prefix in the tooltip value.
      Returns:
      Prefix in the tooltip value or null if not specified

    • setTooltipPrefix

      public Sparkline setTooltipPrefix(String tooltipPrefix)
      Sets the prefix in the tooltip value.
      Parameters:
      tooltipPrefix - Tooltip value prefix If null is set, the tooltip value has no prefix.
      Returns:
      Sparkline component

    • getTooltipSuffix

      public String getTooltipSuffix()
      Gets tooltip value suffix.
      Returns:
      Tooltip value suffix or null if not specified

    • setTooltipSuffix

      public Sparkline setTooltipSuffix(String tooltipSuffix)
      Sets the suffix in the tooltip value.
      Parameters:
      tooltipSuffix - Tooltip value suffix If null is set, no tooltip value suffix is displayed.
      Returns:
      Sparkline component

    • getTooltipChartTitle

      public String getTooltipChartTitle()
      Gets the tooltip header text.
      Returns:
      Tooltip header text or null if no tooltip header text is specified

    • setTooltipChartTitle

      public Sparkline setTooltipChartTitle(String tooltipChartTitle)
      Sets the tooltip header text.
      Parameters:
      tooltipChartTitle - Tooltip header text If null is set, no tooltip header text is displayed.
      Returns:
      Sparkline component

    • isComposite

      public boolean isComposite()
      Checks if the component is a composite sparkline component. If true, multiple sparkline components are integrated into a single sparkline component.
      Returns:
      If true, the component is a composite one, otherwise false

    • getTooltipFormat

      public String getTooltipFormat()
      Gets tooltip format.
      Returns:
      Tooltip format or null if not specified

    • setTooltipFormat

      public Sparkline setTooltipFormat(String tooltipFormat)
      Sets the tooltip format as a JavaScript.
      Parameters:
      tooltipFormat - Format
      See Also:

    • getColumn

      public DataDescriptorColumn getColumn()
      Gets the DataDescriptor column for the component value.
      Returns:
      The DataDescriptor column instance used to build the component or null

    • setIdFieldName

      public Sparkline setIdFieldName(String fieldName)
      Sets the DataDescriptor column name. The DataDescriptor column identifies the data set to be displayed.
      Parameters:
      fieldName - DataDescriptor column name referencing the data set to be displayed
      Returns:
      Sparkline component

    • getIdFieldName

      public String getIdFieldName()
      Gets the DataDescriptor column name referencing the data set to be displayed.
      Returns:
      DataDescriptor column name referencing the data set to be displayed or null if not set

    • setAutoFetchData

      public Sparkline setAutoFetchData(boolean autoFetch)
      Sets if the component automatically queries the data from the database upon being displayed. By default, the component automatically queries the displayed data from the database.
      Specified by:
      setAutoFetchData in interface Fetchable<Sparkline>
      Parameters:
      autoFetch - If true, the component automatically queries data upon being displayed If false, data are not automatically queried. Data query must be implemented by calling the fetchData() method.
      Returns:
      Sparkline component

    • isAutoFetchData

      public boolean isAutoFetchData()
      Checks if data query is automatically performed.
      Specified by:
      isAutoFetchData in interface Fetchable<Sparkline>
      Returns:
      If true, data query is performed automatically Otherwise false.

    • setCustomFetch

      public Sparkline setCustomFetch(FetchEvent fetchEvent)
      Sets a custom query. When calling the fetchData method, the specified FetchEvent implementation is called, then callback methods are run on records returned by the onFetch method.
      Parameters:
      fetchEvent - Custom query implementation

    • fetch

      public List<Record> fetch(int startRow, int endRow, Criteria criteria, List<Order> orders, Client client) throws FindException, DataAccessException
      Description copied from interface: Fetchable
      This method implements actual data retrieval. The Fetchable.fetchData() function runs callback methods on the returned records.
      Specified by:
      fetch in interface Fetchable<Sparkline>
      Parameters:
      startRow - The first row of the query that appears in the returned list
      endRow - The last row of the query that appears in the returned list
      criteria - The criteria used during the query If null, no criteria will be used, every record is queried.
      orders - The orderings that will be applied to the query results. If null, the data will not be ordered.
      client - The client that started the query. If null, the query will happen without checking for access rights.
      Returns:
      The list of records that meet the specified filter criteria.
      Throws:
      FindException - Occurs if an error was encountered during the query
      DataAccessException - Occurs if the user in the specified client has no access to read the data