ChartComponent

class ChartComponent

This class contains all the functionality to create and control chart components.

Please see components/chart for information on how to use this class.

See components-intro for an introduction on how to use components.

setLabelExpression($name, $labelExpression, $options)

Set the label expression for DataSource-backed charts

The label expression is a SQL Expression which is used to find the labels on the chart to display (The labels are on the X-Axis)

For example, in a chart to show “Sales for each category” in a Database table containing sales, the distinct values from “category” column will be shown on the X-Axis. This means that “category” is the Label Expression

Parameters:
  • $name (string) – The name of the X-Axis
  • $labelExpression (DBExpression) – The label expression
  • $options (ChartLabelOptions) – The options for the chart labels
addSeries($name, $expression, $options)

Add a series to a DataSource-backed Chart. You can add multiple series to a chart by calling this function again.

The Series Expression is a SQL Expression which corresponds to a numeric expression which will be displayed on the chart.

For example, if you want to show a chart of “Sales by Category” in a sales table, then you can use the column containing “Sales” as the series expression.

NOTE: the series expressions passed to this function are aggregated by default. To disable aggregation, set 'aggregate'=>false in the options

Parameters:
  • $name (string) – The name of the series
  • $expression (DBExpression) – The series expression
  • $options (ChartSeriesOptions) – The options for the series
addStaticSeries($name, $dataPoints, $options)

Add a series to a static chart. You can add multiple series by calling this function more than once.

The data points of a series have to be a PHP array of numeric values, which will be displayed on the chart as a series. Please ensure that the number of data points in each series is the same as the number of labels set with setStaticLabels

Parameters:
  • $name (string) – The name of the series to be displayed in the legend
  • $dataPoints (array) – An array of numeric values for the series
  • $options (SeriesOptions) – Options for the series
setStaticLabels($name, $labels, $labelArrayOptions)

Set the labels for a static chart.

Note: Please ensure that the number of labels is the same as the number of datapoints in each series

Parameters:
  • $name (sting) – The name of the X-Axis
  • $labels (array) – A PHP array of labels
  • $labelArrayOptions (ChartLabelOptions) – Options for the label
setYAxis($name, $options)

Set the name and options for the Y-Axis of the Chart

Parameters:
  • $name (string) – The name of the Y-Axis
  • $options (ChartAxisOptions) – Options for this axis
setSecondYAxis($name, $options)

Create and configure a secondary Y-Axis for use in a chart.

Note that in order for a series to use this axis, you need to specify that the second Y-Axis must be used inside the Series Options.

For example

$chart->addSeries("Sales", "Table.SalesAmount", array('onSecondYAxis' => true))
Parameters:
  • $name (string) – Name of the second Y-Axis
  • $options (ChartAxisOptions) – Options for this Axis
onSeriesClicked($callback, $target, $eventOptions)

Perform an action when a series is clicked inside the chart. Register a callback function with $callback, which can be used to modify the target.

Parameters:
  • $callback (function) –
  • $target (Component) –
  • $eventOptions (array|EventOptions) –

AutoLink this chart to another component. When a series on this chart is clicked, The target component will be filtered automatically according to the series and label that the user selected.

Parameters:
  • $target (Component) – The component to link to.
  • $options (EventOptions) – Options for the auto link
addTrendLine($name, $value, $color='auto')

Add a Trend Line to the Chart. Trend lines are horizontal lines spanning the chart canvas which aid in interpretation of data with respect to some pre-determined value.

Parameters:
  • $name (string) – The name of the Trendline
  • $value (numeric) – The value at which the trendline is displayed
  • $color=’auto’ (string) – The color, in Hexadecimal sring format, without a # in the beginning
getOptionClassName()
getObjectType()
addSQLWhere($exp, $boolOperand)

Add a SQL WHERE clause to this component.

1. The contents of the expression are not Escaped or binded to prepared queries. Using this function in a non-secure manner may open up your dashboard to SQL Injection vulnerabilities. 2. This condition is only applied to this specific component, not to other components.

Parameters:
  • $exp (string) – The expression to add to the SQL Queries
  • $boolOperand (string) – The boolean operand for the condition. (“AND”/”OR)
sortOn($exp, $sortOrder)

Sort the data in the component based on a particular expression. This is equivalent to having an “ORDER BY” clause in your SQL Queries.

However, this function might not work as expected in components which have data aggregated and grouped by another column. If this is the case, you should use the in-built sorting functionality of the component itself.

1. The contents of the expression are not Escaped or binded to prepared queries. Using this function in a non-secure manner may open up your dashboard to SQL Injection vulnerabilities. 2. This condition is only applied to this specific component, not to other components.

Parameters:
  • $exp (string) – The expression to sort by
  • $sortOrder (string) – The Sort order (“ASC”/”DESC”)
limitTo($exp, $sortOrder)

Limit the data in the component based on a particular expression. This is equivalent to having an “LIMIT” clause in your SQL Queries.

Parameters:
  • $exp (int) – The number of records to take
  • $sortOrder (int) – The number of records to skip
addCondition($expression, $comparison, $value, $boolOperand)

Add a condition to the component. This is similar to having a “WHERE” clause in your SQL Query, but there are a few differences:

1. The $value parameter is protected against SQL Injection attacks so you do not need to worry about escaping the value. 2. There are specific comparisons that you can perform

The comparison operators you can use are:

  • Equality: “eq”, “==”, “isequalto”, “equals”, “equalto”, “equal”
  • Inequality: “neq”, ”!=”, “isnotequalto”, “notequals”, “notequalto”, “notequal”, “ne”
  • Less than: “lt”, “<”, “islessthan”, “lessthan”, “less”
  • Less than or equal to: “lte”, “<=”, “islessthanorequalto”, “lessthanequal”, “le”
  • Greater Than: “gt”, “>”, “isgreaterthan”, “greaterthan”, “greater”
  • Greater Than or Equal To: “gte”, “>=”, “isgreaterthanorequalto”, “greaterthanequal”, “ge”
  • Starts with: “startswith”
  • Ends wit: “endswith”
  • Contains: “contains”
Parameters:
  • $expression (string) – The column or expression to filter
  • $comparison (string) – The comparison operator
  • $value (mixed) – The value to compare against
  • $boolOperand (string) – The boolean operand (AND/OR)
addInitialCondition($expression, $comparison, $value, $boolOperand)

Add a condition which is only applied if there isn’t a drilldown.

Identical behavior to Component::addCondition

Parameters:
  • $expression (string) – The column or expression to filter
  • $comparison (string) – The comparison operator
  • $value (mixed) – The value to compare against
  • $boolOperand (string) – The boolean operand (AND/OR)
setDataSource($datasource)

Set the DataSource for this component.

The DataSource contains information on where to access the data to display in the component.

Parameters:
setCaching()

This function is Not Supported currently

addPostProcessRowCallback($callback)

After processing data (querying, fetching, filtering, etc), you can register a callback to be called with each row. Note that the callback can modify any row and return the final row.

Let’s say that you have a pie chart, but your database has values 0 and 1. You want to rewrite labels 0 => “Not Available” and 1 => “Available” you can add a callback like this

$pieChart->addPostProcessCallback('rewrite_labels');

function rewrite_labels ($row, $sourceComponent) { if($row[‘rfLabels’] === ‘0’) { $row[‘rfLabels’] = “Not Available”; } else if($row[‘rfLabels’] === ‘1’) { $row[‘rfLabels’] = “Available”; } return $row; // Don’t forget this }

Parameters:
  • $callback (function) – A function or name of function to execute
log($message)
Parameters:
  • $message (string) – The message to log
setOption()

Sets one or more options for this component.

You can call setOption in the following ways:

  1. With two params:

$component->setOption(‘caption’, “Hello!”);

  1. As an array of key-value pairs

$component->setOption (array( ‘caption’ => “Hello”, ‘numberPrefix’ => ‘$’ ));

3. As an object of the Options class for the component you’re using. for example, if you’re using it to configure a chart component, you can say

$opt = new ChartOptions();
$opt->caption = "hello";
$opt->numberPrefix = "$";
$component->setOption($opt);
setCaption($caption)

Set the caption for this component.

Parameters:
  • $caption (string) –
setPlaceholder(string)
Parameters:
  • string ($caption) – caption
setWidth($width)

Set the width class for this component.

The width can be 1 to 4.

See dimensions for more information on this

Parameters:
  • $width (int) – The width in Units of 1 to 4
setHeight($width)

Set the height class for this component.

See dimensions for more information on this

Parameters:
  • $width (int) – The height in Units
setDimensions($width, $height)

Set the dimensions for this component

The width can be between 1 to 4.

See dimensions for more information.

Parameters:
  • $width (int) – The width
  • $height (int) – The height
getID()
property autoRangeDrill

A flag for auto range drill. Will cause automatic drilldown when charts are clicked if it is set to true

Type: bool
Default: false
property ID

The ID of the object.

Every instance of the inherited cass created in a request will have a different ID

However, IDs are sequentially generated. So It’s certain that a script with multiple instances of a class

Type: string
Default: “(unset)”

Start building interactive, mobile-friendly Dashboards in PHP. See DemosDownload