Options in RazorFlow

Options are used to customize the functionality and behavior of your components and dashboards.

For example, options can be used to do things like:

  • Change the text alignment in tables.
  • Change the color of the bars in the chart.
  • Change the aggregate function while aggregating data.

Introduction

Take a look at this simple dashboard. All it has is a single chart with two series with two data points each. Do not worry about the specific API Calls. They aren’t relavant to the current discussion.

A Simple Dashboard

<?php
require "../razorflow.php";

Dashboard::setTitle("RazorFlow Component Options");

// Create and configure a chart component
$chart = new ChartComponent();
$chart->setCaption("Chart");
$chart->setStaticLabels("Labels", array("A", "B"));

$chart->addStaticSeries("Series 1", array(10, 20));
$chart->addStaticSeries("Series 2", array(15, 10));

Dashboard::addComponent($chart);
Dashboard::Render();

To demonstrate how options are set, you are going to change the colors of the series. Note that the default colors are set based on the theme, and depending on the default theme that you’ve chosen, you may see different colors.

Options Object

Make a modification to the previous example, and set the color of Series 1 to the Hex code A4C9F3. It’s a Light Blue color. The code that’s been modified is highlighted.

Setting an option

<?php
require "../razorflow.php";

Dashboard::setTitle("RazorFlow Component Options");

// Create and configure a chart component
$chart = new ChartComponent();
$chart->setCaption("Chart");
$chart->setStaticLabels("Labels", array("A", "B"));

$opts = new ChartSeriesOptions();
$opts->color = "A4C9F3";

$chart->addStaticSeries("Series 1", array(10, 20), $opts);
$chart->addStaticSeries("Series 2", array(15, 10));

Dashboard::addComponent($chart);
Dashboard::Render();

Let’s examine the modification more carefully

$opts = new ChartSeriesOptions();
$opts->color = "A4C9F3";

$chart->addArraySeries("Series 1", array(10, 20), $opts);

You are creating a variable $opts which is an object of the class ChartSeriesOptions. This is an Options Object. You set the color property on the Options Object.

Next, you pass the $opts variable to the ChartComponent::addArraySeries function as an argument. This is passed only while configuring “Series 1” and not “Series 2” - so Series 2 has the default color.

Options Array

Options are used quite extensively in all dashboards made with RazorFlow Dashboards for PHP. And in order to make it easier to build and write, you can use the Shorthand Notation of setting options.

For example, if you wanted to implement the same functionality in the earlier section using shorthand notation, it would look like:

Shorthand notation

<?php
require "../razorflow.php";

Dashboard::setTitle("RazorFlow Component Options");

// Create and configure a chart component
$chart = new ChartComponent();
$chart->setCaption("Chart");
$chart->setStaticLabels("Labels", array("A", "B"));

$chart->addStaticSeries("Series 1", array(10, 20), array(
	'color' => "A4C9F3"
));
$chart->addStaticSeries("Series 2", array(15, 10));

Dashboard::addComponent($chart);
Dashboard::Render();

In the ChartComponent::addArraySeries function, instead of passing an object, you pass a PHP array. The array is a key-value set. The keys are the name of the option that you’re setting and the value should be the corresponding value.

If you examine the highlighted code

$chart->addArraySeries("Series 1", array(10, 20), array(
        'color' => "A4C9F3"
));

It’s just a single statement written over three lines for clarity. But you can also write it as

$chart->addArraySeries("Series 1", array(10, 20), array('color'=>'A4C9F3'));

or you can declare the array externally

$options = array('color'=>'A4C9F3');
$chart->addArraySeries("Series 1", array(10, 20), $options);

or even

$options = array();
$options['color'] = 'A4C9F3';
$chart->addArraySeries("Series 1", array(10, 20), $options);

Setting Defaults

You can easiliy override the defaults with your own, which are effective for the entire dashboard. Like this:

Setting defaults

<?php
require "../razorflow.php";

Dashboard::setTitle("Default Options");

// Create and configure a chart component
$chart = new ChartComponent();
$chart->setCaption("Chart");
$chart->setStaticLabels("Labels", array("A", "B"));

Dashboard::setDefaults("ChartSeriesOptions", array(
	'color' => "A4C9F3"
));

$chart->addStaticSeries("Series 1", array(10, 20));
$chart->addStaticSeries("Series 2", array(15, 10));

Dashboard::addComponent($chart);
Dashboard::Render();

We are calling the Dashboard::setDefaults function. Note that this is not called on any particular chart. But it affects the entire dashboard at once

Dashboard::setDefaults("ChartSeriesOptions", array(
        'color' => "A4C9F3"
));

The first argument to Dashboard::setDefaults is the name of the option class. You can find the name of the option class that a function accepts in the API Documentation. For example, in ChartComponent::addArraySeries, you can see that it’s a ChartSeriesOptions class.

You can also override the defaults that you set inside any function which accepts the options. For example:

Overriding defaults

<?php
require "../razorflow.php";

Dashboard::setTitle("Default Options");

// Create and configure a chart component
$chart = new ChartComponent();
$chart->setCaption("Chart");
$chart->setStaticLabels("Labels", array("A", "B"));

Dashboard::setDefaults("ChartSeriesOptions", array(
	'color' => "A4C9F3"
));

$chart->addStaticSeries("Series 1", array(10, 20), array('color' => 'F3A7A4'));
$chart->addStaticSeries("Series 2", array(15, 10));

Dashboard::addComponent($chart);
Dashboard::Render();

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