/**
* Sets the callback for an event.
*
* @access public
* @param string $event
* @param string $callback
* @throws \Khill\Lavacharts\Exceptions\InvalidEvent
* @throws \Khill\Lavacharts\Exceptions\InvalidEventCallback
*/
public function set($event, $callback)
{
$this->validEvent($event);
if (Utils::nonEmptyString($callback) === false) {
throw new InvalidEventCallback($callback);
}
$this->events[$event] = $callback;
}
/**
* Builds the Event object.
*
* @param string $c Name of Javascript callback function.
* @throws InvalidConfigValue
* @return Event
*/
public function __construct($c)
{
if (Utils::nonEmptyString($c)) {
$this->callback = $c;
} else {
throw new InvalidConfigValue('an Event', 'string');
}
}
/**
* Builds a new Filter Object.
*
* Takes either a column label or a column index to filter. The options object will be
* created internally, so no need to set defaults. The child filter objects will set them.
*
* @param string|int $columnLabelOrIndex
* @param array $config Array of options to set.
* @throws \Khill\Lavacharts\Exceptions\InvalidConfigValue
*/
public function __construct($columnLabelOrIndex, $config = [])
{
if (Utils::nonEmptyString($columnLabelOrIndex) === false && is_int($columnLabelOrIndex) === false) {
throw new InvalidConfigValue(static::TYPE . '->' . __FUNCTION__, 'string|int');
}
if (is_string($columnLabelOrIndex) === true) {
$config = array_merge($config, ['filterColumnLabel' => $columnLabelOrIndex]);
}
if (is_int($columnLabelOrIndex) === true) {
$config = array_merge($config, ['filterColumnIndex' => $columnLabelOrIndex]);
}
$this->options = new Options($config);
}
/**
* Parses a datetime string with or without a datetime format.
*
* Uses Carbon to create the values for the DateCell.
*
*
* @param string $dateTimeString
* @param string $dateTimeFormat
* @return \Khill\Lavacharts\DataTables\Cells\Cell
* @throws \Khill\Lavacharts\Exceptions\FailedCarbonParsing
* @throws \Khill\Lavacharts\Exceptions\InvalidDateTimeFormat
* @throws \Khill\Lavacharts\Exceptions\InvalidDateTimeString
*/
public static function parseString($dateTimeString, $dateTimeFormat = '')
{
if (Utils::nonEmptyString($dateTimeString) === false) {
throw new InvalidDateTimeString($dateTimeString);
}
if (gettype($dateTimeFormat) != 'string') {
throw new InvalidDateTimeFormat($dateTimeFormat);
}
if (Utils::nonEmptyString($dateTimeFormat) === false) {
$carbon = Carbon::parse($dateTimeString);
} else {
$carbon = Carbon::createFromFormat($dateTimeFormat, $dateTimeString);
}
return new DateCell($carbon);
}
/**
* Simple true/false test if a chart exists.
*
* @param string $type Type of chart to store.
* @param string $label Identifying label of a chart to check.
*
* @return bool
*/
public function checkChart($type, $label)
{
if (Utils::nonEmptyString($type) && Utils::nonEmptyString($label)) {
if (array_key_exists($type, $this->charts)) {
if (array_key_exists($label, $this->charts[$type])) {
return true;
} else {
return false;
}
} else {
return false;
}
} else {
return false;
}
}
/**
* Creates a new column object.
*
* @access public
* @since 3.0.0
* @param string $type Type of column to create.
* @param string $label A label for the column.
* @param \Khill\Lavacharts\DataTables\Formats\Format $format Column formatter for the data.
* @param string $role A role for the column to play.
* @return \Khill\Lavacharts\DataTables\Columns\Column
* @throws \Khill\Lavacharts\Exceptions\InvalidColumnRole
* @throws \Khill\Lavacharts\Exceptions\InvalidColumnType
*/
public static function create($type, $label = '', Format $format = null, $role = '')
{
if (Utils::nonEmptyStringInArray($type, self::$TYPES) === false) {
throw new InvalidColumnType($type, self::$TYPES);
}
$columnArgs = [$type];
if (Utils::nonEmptyString($label) === true) {
$columnArgs[] = $label;
} else {
$columnArgs[] = '';
}
if ($format !== null) {
$columnArgs[] = $format;
} else {
$columnArgs[] = null;
}
if (is_string($role) === false || $role != '' && in_array($role, self::$ROLES, true) === false) {
throw new InvalidColumnRole($role, self::$ROLES);
}
$columnArgs[] = $role;
$column = new \ReflectionClass('\\Khill\\Lavacharts\\DataTables\\Columns\\Column');
return $column->newInstanceArgs($columnArgs);
}
/**
* Checks the Chart for DataTable and builds the Javascript code block
*
* Build the script block for the actual chart and passes it back to
* output function of the calling chart object. If there are any
* events defined, they will be automatically be attached to the chart and
* pulled from the callbacks folder.
*
* @access public
*
* @uses Chart
* @param Chart $chart Chart object to render.
* @param string $elementId HTML element id to output the chart into.
* @throws DataTableNotFound
* @throws InvalidElementId
*
* @return string Javascript code block.
*/
public function getChartJs(Chart $chart, $elementId = null)
{
if (isset($chart->datatable) === false) {
throw new DataTableNotFound($chart);
}
if (Utils::nonEmptyString($elementId) === false) {
throw new InvalidElementId($elementId);
}
$this->chart = $chart;
$this->elementId = $elementId;
return $this->buildChartJs();
}
/**
* Simple true/false test if a chart exists.
*
* @param string $type Type of chart to check.
* @param \Khill\Lavacharts\Values\Label $label Identifying label of a chart to check.
* @return boolean
*/
public function checkChart($type, Label $label)
{
if (Utils::nonEmptyString($type) === false) {
return false;
}
if (array_key_exists($type, $this->charts) === false) {
return false;
}
return array_key_exists((string) $label, $this->charts[$type]);
}
/**
* Custom json serialization of the column.
*
* @access public
* @return array
*/
public function jsonSerialize()
{
$values = ['type' => $this->type];
if (Utils::nonEmptyString($this->label) === true) {
$values['label'] = $this->label;
}
if (Utils::nonEmptyString($this->role) === true) {
$values['p'] = ['role' => $this->role];
}
return $values;
}
/**
* Specifies how to scale the axis to render the values within
* the chart area. The following string values are supported:
*
* 'pretty' - Scale the values so that the maximum and minimum
* data values are rendered a bit inside the left and right of the chart area.
* 'maximized' - Scale the values so that the maximum and minimum
* data values touch the left and right of the chart area.
* 'explicit' - Specify the left and right scale values of the chart area.
* Data values outside these values will be cropped. You must specify an
* axis.viewWindow array describing the maximum and minimum values to show.
*
* This option is only supported for a continuous axis.
*
* @param string $viewMode
* @throws InvalidConfigValue
* @return Axis
*/
public function viewWindowMode($viewMode)
{
$values = array('pretty', 'maximized', 'explicit');
if (Utils::nonEmptyString($viewMode) && in_array($viewMode, $values)) {
$this->viewWindowMode = $viewMode;
} else {
throw $this->invalidConfigValue(__FUNCTION__, 'string', 'with a value of ' . Utils::arrayToPipedString($values));
}
return $this;
}
/**
* @dataProvider nonStringProvider
*/
public function testWithBadTypes($badTypes)
{
$this->assertFalse(Utils::nonEmptyString($badTypes));
}
/**
* Sets the value of a string option.
*
* @param string $option Option to set.
* @param string $value Value of the option.
* @return \Khill\Lavacharts\JsonConfig
* @throws \Khill\Lavacharts\Exceptions\InvalidConfigValue
* @throws \Khill\Lavacharts\Exceptions\InvalidOption
*/
protected function setStringOption($option, $value)
{
if (Utils::nonEmptyString($value) === false) {
throw new InvalidConfigValue(static::TYPE . '->' . $option, 'string');
}
$this->options->set($option, $value);
return $this;
}
/**
* Either passes the Carbon instance or parses a datetime string.
*
* @param Carbon|string $date
* @return string Javscript date declaration
*/
private function parseDate($date)
{
if (is_a($date, 'Carbon\\Carbon')) {
$carbonDate = $date;
} elseif (Utils::nonEmptyString($date)) {
try {
if (Utils::nonEmptyString($this->dateTimeFormat)) {
$carbonDate = Carbon::createFromFormat($this->dateTimeFormat, $date);
} else {
$carbonDate = Carbon::parse($date);
}
} catch (\Exception $e) {
throw new InvalidDate();
}
} else {
throw new InvalidDate();
}
return $this->carbonToJsString($carbonDate);
//return $carbonDate->toIso8601String();
}
/**
* Get the value of a set option.
*
* @access public
* @param string $option Name of option.
* @return mixed
* @throws \Khill\Lavacharts\Exceptions\InvalidOption
*/
public function get($option)
{
if (Utils::nonEmptyString($option) === false) {
throw new InvalidOption($option, $this->options);
}
if (array_key_exists($option, $this->values) === false) {
return null;
} else {
return $this->values[$option];
}
}
/**
* Sets the string suffix for the value.
*
* @param string $s
* @throws InvalidConfigValue
* @return NumberFormat
*/
public function suffix($s)
{
if (Utils::nonEmptyString($s)) {
$this->suffix = $s;
} else {
throw new InvalidConfigValue(__FUNCTION__, 'string');
}
return $this;
}
/**
* The color to use for the yellow section, in HTML color notation.
*
* @param string $c
*
* @return GaugeChart
*/
public function yellowColor($c)
{
if (Utils::nonEmptyString($c)) {
return $this->addOption(array(__FUNCTION__ => $c));
} else {
throw $this->invalidConfigValue(__FUNCTION__, 'string');
}
}
/**
* Sets the format to be used by Carbon::createFromFormat()
*
* This method is used to set the format to be used to parse a string
* passed to a cell in a date column, that was parsed incorrectly by Carbon::parse()
*
*
* @access public
* @param string $dateTimeFormat
* @return \Khill\Lavacharts\DataTables\DataTable
* @throws \Khill\Lavacharts\Exceptions\InvalidConfigValue
*/
public function setDateTimeFormat($dateTimeFormat)
{
if (Utils::nonEmptyString($dateTimeFormat) === false) {
throw new InvalidConfigValue(__FUNCTION__, 'string');
}
$this->dateTimeFormat = $dateTimeFormat;
return $this;
}
/**
* Sets the time zone in which to display the date value.
*
* This is a numeric value, indicating GMT + this number of time zones (can be negative).
* Date object are created by default with the assumed time zone of the computer on which they are created;
* this option is used to display that value in a different time zone.
*
* For example, if you created a Date object of 5pm noon on a computer located in Greenwich, England,
* and specified timeZone to be -5 (options['timeZone'] = -5, or Eastern Pacific Time in the US),
* the value displayed would be 12 noon.
*
*
* @param string $tz
* @throws InvalidConfigValue
* @return DateFormat
*/
public function timeZone($tz)
{
if (Utils::nonEmptyString($tz)) {
$this->timeZone = $tz;
} else {
throw new InvalidConfigValue(__FUNCTION__, 'string');
}
return $this;
}
/**
* Checks the Dashboard for DataTable and builds the Javascript code block
*
* Build the script block for the actual dashboard and passes it back to
* output function of the calling chart object. If there are any
* events defined, they will be automatically be attached to the chart and
* pulled from the callbacks folder.
*
* @access public
*
* @uses Dashboard
* @param Bashboard $dashboard Dashboard object to render.
* @param string $elementId HTML element id to output the chart into.
* @throws DataTableNotFound
* @throws InvalidElementId
*
* @return string Javascript code block.
*/
public function getDashboardJs(Dashboard $dashboard, $elementId = null)
{
if (isset($dashboard->datatable) === false) {
throw new DataTableNotFound($dashboard);
}
if (Utils::nonEmptyString($elementId) === false) {
throw new InvalidElementId($elementId);
}
$this->dashboard = $dashboard;
$this->elementId = $elementId;
return $this->buildDashboardJs();
}
public function setElementId($elementId)
{
if (Utils::nonEmptyString($elementId) === false) {
throw new InvalidElementId($elementId);
}
$this->elementId = $elementId;
}
/**
* Magic function to reduce repetitive coding and create aliases.
*
* @access public
* @since v1.0.0
*
* @param string $member Name of method
* @param array $arguments Passed arguments
* @throws InvalidLavaObject
* @throws InvalidChartLabel
*
* @return mixed Returns Charts, DataTables, and Config Objects
*/
public function __call($member, $arguments)
{
if ($this->strStartsWith($member, 'render')) {
$chartType = str_replace('render', '', $member);
if (in_array($chartType, $this->chartClasses)) {
return $this->render($chartType, $arguments[0], $arguments[1]);
} else {
throw new InvalidLavaObject($chartType);
}
}
if ($member == 'DataTable') {
if (isset($arguments[0])) {
return new Configs\DataTable($arguments[0]);
} else {
return new Configs\DataTable();
}
}
if (in_array($member, $this->chartClasses)) {
if (isset($arguments[0])) {
if (Utils::nonEmptyString($arguments[0])) {
return $this->chartFactory($member, $arguments[0]);
} else {
throw new InvalidChartLabel($arguments[0]);
}
} else {
throw new InvalidChartLabel();
}
}
if (in_array($member, $this->configClasses)) {
if (isset($arguments[0]) && is_array($arguments[0])) {
return $this->configFactory($member, $arguments[0]);
} else {
return $this->configFactory($member);
}
}
if (in_array($member, $this->formatClasses)) {
if (isset($arguments[0]) && is_array($arguments[0])) {
return $this->formatFactory($member, $arguments[0]);
} else {
return $this->formatFactory($member);
}
}
if (in_array($member, $this->eventClasses)) {
if (isset($arguments[0])) {
if (Utils::nonEmptyString($arguments[0])) {
return $this->eventFactory($member, $arguments[0]);
} else {
throw new InvalidEventCallback($arguments[0]);
}
} else {
throw new InvalidEventCallback();
}
}
if (!method_exists($this, $member)) {
throw new InvalidLavaObject($member);
}
}
/**
* Parses a DataTable into a CSV file.
*
* Pass in a DataTable and a csv file will be generated.
*
* @access public
* @since 1.0.0
* @param string $filepath Path where to output the file
* @throws \Khill\Lavacharts\Exceptions\InvalidFunctionParam
* @return string
*/
public function toCsv($filepath)
{
if (Utils::nonEmptyString($filepath) === false) {
throw new InvalidFunctionParam($filepath, __FUNCTION__, 'string');
}
$csv = Writer::createFromFileObject(new \SplTempFileObject());
$csv->insertOne($this->getColumnLabels());
foreach ($this->rows as $row) {
$rowData = [];
foreach ($row['c'] as $data) {
$rowData[] = $data['v'];
}
$csv->insertOne($rowData);
}
$csv->output($filepath);
}
/**
* Renders the dashboard into the page
*
* Given a dashboard label and an HTML element id, this will output
* all of the necessary javascript to generate the chart.
*
* @access public
* @since v2.0.0
*
* @param string $dashboardType Type of dashboard to render.
* @param string $dashboardLabel Label of a saved chart.
* @param string $elementId HTML element id to render the chart into.
* @param mixed $divDimensions Set true for div creation, or pass an array with height & width
*
* @return string
*/
public function renderDashboard($dashboardType, $dashboardLabel, $elementId = null, $divDimensions = false)
{
$jsOutput = '';
$dashboard = $this->volcano->getDashboard($dashboardType, $dashboardLabel);
if (!empty($elementId) && Utils::nonEmptyString($elementId)) {
$dashboard->setElementId($elementId);
}
if ($this->jsFactory->coreJsRendered() === false) {
$jsOutput = $this->jsFactory->getCoreJs();
$this->jsFactory->coreJsRendered(true);
}
if ($divDimensions !== false) {
$jsOutput .= $this->div($dashboard->elementId, $divDimensions);
}
$jsOutput .= $this->jsFactory->getDashboardJs($dashboard, $elementId);
return $jsOutput;
}
/**
* Register javascript callbacks for specific events.
*
* Set with an associative array where the keys are events and the values are the
* javascript callback functions.
*
* Valid events are:
* [ animationfinish | error | onmouseover | onmouseout | ready | select | statechange ]
*
* @access public
* @param array $events Array of events associated to a callback
* @return \Khill\Lavacharts\Charts\Chart
* @throws \Khill\Lavacharts\Exceptions\InvalidConfigValue
*/
public function events($events)
{
if (is_array($events) === false) {
throw new InvalidConfigValue(static::TYPE . '->' . __FUNCTION__, 'array', 'who\'s keys are one of ' . Utils::arrayToPipedString($this->defaultEvents));
}
foreach ($events as $event => $callback) {
if (Utils::nonEmptyString($callback) === false) {
throw new InvalidConfigValue(static::TYPE . '->' . __FUNCTION__, 'string');
}
$this->events->set($event, $callback);
}
return $this;
}
/**
* Overrides the default format for various aspects of date/datetime/timeofday data types.
*
* Allows formatting for years, months, days, hours, minutes, seconds, and milliseconds.
*
* @param array $units
* @return \Khill\Lavacharts\Configs\Gridlines
* @throws \Khill\Lavacharts\Exceptions\InvalidConfigValue
*/
public function units($units)
{
$unitFormats = [];
$unitValues = ['years', 'months', 'days', 'hours', 'minutes', 'seconds', 'milliseconds'];
if (is_array($units) === false) {
throw new InvalidConfigValue(__FUNCTION__, 'array');
}
foreach ($units as $unit => $format) {
if (is_string($unit) === false || in_array($unit, $unitValues) === false) {
throw new InvalidConfigValue(__FUNCTION__, 'string', 'Valid unit values are ' . Utils::arrayToPipedString($unitValues));
}
if (Utils::nonEmptyString($format) === false) {
throw new InvalidConfigValue(__FUNCTION__, 'string');
}
$unitFormats[$unit] = $format;
}
return $this->setOption(__FUNCTION__, $unitFormats);
}
