Skip to content

Latest commit

 

History

History
815 lines (614 loc) · 21.5 KB

README.md

File metadata and controls

815 lines (614 loc) · 21.5 KB
Raw

PHP Wrapper for ZingChart

The purpose of this wrapper is to enable PHP users to quickly and easily create interactive charts using nothing but PHP code. No JavaScript required.

Initial Setup

Manual

  1. Download this repo by clicking on the green "Clone or download" button near the top of this page.
  2. Click on "Download Zip" option to begin the download.
  3. Copy file "ZC.php" into your project's source directory.
  4. Include the ZingChart library in your project <script src="//cdn.zingchart.com/zingchart.min.js"></script>.
  5. Include this wrapper in your project using the 'include' syntax. ie) include ZC.php.
  6. After the include use the proper namespace in your code: use ZingChart\PHPWrapper\ZC;.
include 'ZC.php';
use ZingChart\PHPWrapper\ZC;

$datay = array();
$a = 6.619;
$b = 0.113;
$index = 0;
for ($x = 50; $x < 600; $x += 50, $index++) {
    array_push($datay, $a + $b*$x);
}

$zc = new ZC("myChart");
$zc->setChartType("line");
$zc->setTitle("PHP 5.6 render");
$zc->setSeriesData(0, $datay);
$zc->setChartHeight("400px");
$zc->setChartWidth("100%");
$zc->render();

Composer

We are on Packagist here.

  1. Download this package with Composer: composer require zingchart/php_wrapper.
  2. AutoLoad your package dependencies in your project: require __DIR__ . '/vendor/autoload.php;.
  3. Reference this library in your code: use ZingChart\PHPWrapper\ZC;.

Quick Start

Pulling plot data from MySQL:

$zc = new ZC("myChart");
$zc->connect($host,$port,$uName,$pswd,$db);
$data = $zc->query($mySqlQuery, true);
$zc->setSeriesData($data[1]);
$zc->render();
$zc->closeConnection();

Code Breakdown:

  1. $zc = new ZC("myChart");
    Instantiate a new instance of the ZC object with the id of the html element you wish to embed your chart in. For example, <div id="myChart"></div>.
  2. $zc->connect($host,$port,$uname,$pswd,$db);
    Establish a connection to your db.
  3. $data = $zc->query($mySqlQuery, $scaleXLabelsFlag);
    Query the db with a valid SQL query string and set returned value to a variable.
    Note: The second argument to this function accepts a boolean that tells this function whether the first field returned from the SQL query should be treated as the scaleXLabels.
  4. $zc->setSeriesData($data[1]);
    Set the plot data with the data stored from your sql query, ie. $data[1] is the plot data and $data[0] in this case holds the x-axis scale labels. This is because we set the $scaleXLabelsFlag to 'true' so our first dataset in our array will hold these labels in an array at index 0. And the plot data is stored in another array at index 1.
  5. $zc->render();
    Render your data as the default 'Area' chart type. If you wish to use a different chart type then simply set it either using another function call $zc->setChartType("bar"); or via overloading the constructor method $zc = new ZC("myChart", "bar");.
  6. $zc->closeConnection();
    Be sure to close your database connection once you are done using it.

Plotting data without a MySQL database:

$zc = new ZC("myChart");
$zc->setSeriesData([1,4,2,6,3]);
$zc->render();

Code Breakdown:

  1. $zc = new ZC("myChart");
    Instantiate a new instance of the ZC object with the id of the html elemet you wish to embed your chart in. For example, <div id="myChart"></div>.
  2. $zc->setSeriesData(0, [1,4,2,6,3]);
    Set the plot data with an array of values. You can even use an array of arrays to plot multiple series like this: $zc->setSeriesData([[12,35,24],[3,9,7]);
  3. $zc->render();
    Render your data as the default 'Area' chart type. If you wish to use a different chart type then simply set it either using another function call $zc->setChartType("bar"); or via overloading the constructor $zc = new ZC("myChart", "bar");.

Live Demos

Usage

Constructor:
ZC - The constructor for ZingChart. Overloading is possible.

There are three levels of usability for this wrapper:

Documentation

ZC ( elemId [,chartType="area" [,theme="light" [,width="100%" [,height="400"]]]] ) Contructor

Default Behavior: This method is overloaded to accept: 1, 2, 3, 4, or 5 arguments. Argument order matters. See examples below.

Examples:

$zc = new ZC("chartDiv");
$zc = new ZC("chartDiv", "line");
$zc = new ZC("chartDiv", "line", "dark");
$zc = new ZC("chartDiv", "line", "dark", "600");
$zc = new ZC("chartDiv", "line", "dark", "600", "400");
$zc = new ZC("chartDiv", null, "dark");
$zc = new ZC("chartDiv", "bar", null, 600, 400);

NOTE: The first argument is required to render your chart properly. This first argument corresponds to the id of the html element you wish to put your chart into.

render ( ) Level 1

Renders the chart to the html element specified from the constructor.

Example:

$zc->render();

getRenderScript ( ) Level 1

This function returns the text that would be printed by the render function.

Example:

$chart1Script = $zc->getRenderScript();// This stores the script, to be printed later
echo $chart1Script;// This will render the chart

connect ( host, port, username, pswd, db ) Level 1

Establishes a connection to your MySQL database.

Example:

$zc->connect("127.0.0.1","8889","root","root","mydb");

closeConnection ( ) Level 1

Closes the connection to your MySQL database.

Example:

$zc->closeConnection();

query ( sqlQuery, scaleXLabelsFlag ) Level 1

Queries your MySQL database with your supplied query string. Note: Accepts a second argument that expects a boolean representing whether or not to treat the first field returned from your SQL query as the x-axis scale labels.

Example:

$queryStr = "SELECT timestamp, unitsSold, expected, anotherMetric FROM feed_data";
$zc->query($queryStr, true);

In the code snippet above, we set the scaleXLabelsFlag to true because our SQL query returns 'timestamps' data that we wish to set as our x-axis scale labels. If we did not want to explicitly set the x-axis labels then the code could look like this:

$queryStr = "SELECT unitsSold, expected, anotherMetric FROM feed_data";
$zc->query($queryStr, false);

getFieldNames ( ) Level 1

Get the MySQL field names returned from the function query above.

Example:

$fieldNames = $zc->getFieldNames();

setTitle ( theChartTitle ) Level 1

Sets the chart title. Expected arg: String.

Example:

$zc->setTitle("Sandwiches Consumed");

setSubtitle ( theSubtitle ) Level 1

Sets the chart subtitle. Expected arg: String.

Example:

$zc->setSubtitle("March 1 thru March 31, 2016");

setLegendTitle ( theLegendTitle ) Level 1

Sets the chart legend's title. Expected arg: String.

Example:

$zc->setLegendTitle("Sandwich Types");

setScaleXTitle ( xAxisTitle ) Level 1

Sets the chart x-axis title.

Example:

$zc->setScaleXTitle("Quantity");

setScaleYTitle ( yAxisTitle ) Level 1

Sets the chart y-axis title.

Example:

$zc->setScaleYTitle("Date");

setScaleXLabels ( xAxisLabels ) Level 1

Sets the chart x-axis' scale values.

Example:

$zc->setScaleXLabels(array("Mar 1", "Mar 2", "Mar 3));

setScaleYLabels ( yAxisValueRange ) Level 1

Sets the chart y-axis' scale value range and increment.

Example:

$zc->setScaleYLabels(array("0:10:100");

setSeriesData ( [,seriesIndex], plotDataArray ) Level 1

Sets the chart plot data. ie) The data to be plotted. seriesIndex is an optional parameter. If ommited, the function will assume plotDataArray contain all the data for all the series.

Examples:

$zc->setSeriesData(0, [5,7,11]);
$zc->setSeriesData([[3,7,1], [20,32,37], [1,25,48]]);

setSeriesText ( [,seriesIndex], seriesText ) Level 1

Sets the chart data labels. ie) Used for tooltips, valueBox, etc.. There are two ways to overload this function.

  1. One argument - ([]) : an array of values. Will apply each element of this array to the corresponding series text.
  2. Two arguments - (i, "value") : i is the index of the series to apply "value" towards.

Examples:

$zc->setSeriesText(["BLT","Tuna","Club"]); // applies "BLT" to series[0], "Tuna" to series[1],..
$zc->setSeriesText(0, "BLT");              // applies "BLT" to series[0]

setChartType ( theType ) Level 1

Sets the chart type. ie) Area, Bar, Line, Pie, etc..

Example:

$zc->setChartType("line");

setChartWidth ( chartWidth ) Level 1

Sets the chart width. Note: Defaults to 100%.

Examples:

$zc->setChartWidth("600"); // in pixels
$zc->setChartWidth("100%");

setChartHeight ( chartHeight ) Level 1

Sets the chart height. Note: Defaults to 400px.

Examples:

$zc->setChartHeight("400"); // in pixels
$zc->setChartHeight("50%");

setChartTheme ( chartTheme ) Level 1

Sets the chart color theme. ie) light, dark, classic

Limited Options: "light" | "dark" | "classic"

Example:

$zc->setChartTheme("dark");

setFullscreen ( ) Level 1

Toggles the chart to fit the window. Calling this method twice will disable fullscreen.

Example:

$zc->setFullscreen();

enableScaleXZooming ( ) Level 1

Turn on chart zooming on x-axis.

Example:

$zc->enableScaleXZooming();

enableScaleYZooming ( ) Level 1

Turn on chart zooming on y-axis.

Example:

$zc->enableScaleYZooming();

enableCrosshairX ( ) Level 1

Turn on chart crosshair guide on x-axis. NOTE: On by default.

Example:

$zc->enableCrosshairX();

enableCrosshairY ( ) Level 1

Turn on chart crosshair guide on y-axis.

Example:

$zc->enableCrosshairY();

enableTooltip ( ) Level 1

Turn on chart tooltip.

Example:

$zc->enableTooltip();

enableValueBox ( ) Level 1

Turn on chart valueBox.

Example:

$zc->enableValueBox();

enablePreview ( ) Level 1

Turn on chart preview area.

Example:

$zc->enablePreview();

disableScaleXZooming ( ) Level 1

Turn off chart zooming on x-axis.

Example:

$zc->disableScaleXZooming();

disableScaleYZooming ( ) Level 1

Turn off chart zooming on y-axis.

Example:

$zc->disableScaleYZooming();

disableCrosshairX ( ) Level 1

Turn off chart crosshair on x-axis.

Example:

$zc->disableCrosshairX();

disableCrosshairY ( ) Level 1

Turn off chart crosshair on y-axis.

Example:

$zc->disableCrosshairY();

disableTooltip ( ) Level 1

Turn off chart tooltip.

Example:

$zc->disableTooltip();

disableValueBox ( ) Level 1

Turn off chart valueBox.

Example:

$zc->disableValueBox();

disablePreview ( ) Level 1

Turn off chart preview area.

Example:

$zc->disablePreview();

getTitle ( ) Level 1

Get the chart title.

Example:

$chartTitle = $zc->getTitle();

getSubtitle ( ) Level 1

Get the chart subtitle.

Example:

$chartSubtitle = $zc->getSubtitle();

getLegendTitle ( ) Level 1

Get the chart legend title.

Example:

$legendTitle = $zc->getLegendTitle();

getConfig ( ) Level 1

Get the chart JSON configuration.

Example:

$config = $zc->getConfig();

getScaleXTitle ( ) Level 1

Get the chart x-axis title.

Example:

$xAxisTitle = $zc->getScaleXTitle();

getScaleYTitle ( ) Level 1

Get the chart y-axis title.

Example:

$yAxisTitle = $zc->getScaleYTitle();

getScaleXLabels ( ) Level 1

Get the chart x-axis scale values.

Example:

$xAxisLabels = $zc->getScaleXLabels();

getScaleYLabels ( ) Level 1

Get the cahrt y-axis scale values.

Example:

$yAxisLabels = $zc->getScaleYLabels();

getSeriesData ( ) Level 1

Get the chart plot data/values.

Example:

$plotValues = $zc->getSeriesData();

getSeriesText ( ) Level 1

Get the chart plot data labels/texts.

Example:

$plotSeriesText = $zc->getSeriesText();

setConfig ( ) Level 2

This is a single function that accepts a string in the form of dot-syntax. This function allows you to set a value for a single chart property.

Examples:

$zc->setConfig("legend.header.background-color", "red");
$zc->setConfig("series[1].values", array(5,9,13,10,22,39));

You may also pass in an associative array to set multiple attributes from the given root property like this:

$legendConfig = array(
    "header" => array(
        "background-color" => "red"
    ),
    "marker" => array(
        "border-color" => "orange",
        "border-width" => "3px",
        "shadow-angle" => "115"
    )
);

$zc->setConfig("legend", $legendConfig);

This syntax is a close-derivative of ZingChart's JSON syntax except that it uses dots to represent sub-object navigation.

trapdoor ( ) Level 3

This is a single function that accepts a full-blown JSON string. This function allows you to set the entire chart's configuration with a single function call. This JSON string can be generated using standard PHP associative array syntax as well.

Note: Using the trapdoor will overwrite any previously set chart configurations for that object.

For example, if you set $zc->setLegendTitle("Cool Title") and later use $zc->trapdoor("series":[{"values": [1,2,3]}, {"values":[22,23,27]}) then the legend title will be destroyed.

Examples:

$myConfig = array(
    "legend" => array(
        "header" => array(
            "background-color" => "red"
        ),
        "marker" => array(
            "border-color" => "orange",
            "border-width" => "3px",
            "shadow-angle" => "115"
        )
    ),
    "series" => array(
        array(
            "values" => array(33,45,27,32,15),
            "text"   => "Apples"
        ),
        array(
            "values" => array(1,5,9,3,7),
            "text"   => "Oranges"
        )
    )
);
$zc->trapdoor(json_encode($myConfig));

Or you could pass in the JSON string like this:

$jsonString = <<< EOT
{
    "legend":{
        "header":{
            "background-color":"red"
        },
        "marker":{
            "border-color":"orange",
            "border-width":"3px",
            "shadow-angle":"115"
        }
    },
    "series":[
    {
        "values":[33,45,27,32,15],
        "text":"Apples"
    },
    {
        "values":[1,5,9,3,7],
        "text":"Oranges"
    }]
}
EOT;

$zc->trapdoor($jsonString);

One thing to note here is that if you are using the array method, then you must prepend your array with json_encode(...) in order to render the chart properly when you call the render method.

Finished product:
The following three lines of code will produce an area chart that is 600x400 pixels with the light color theme rendered in the html element's id of 'myChart'.

$zc = new ZC("myChart", "area", "light", 600, 400);
$zc->trapdoor(json_encode($myConfig));
$zc->render();

More Documentation

You may visit our JSON Attributes page for more in-depth tutorials on how to use JSON syntax with ZingChart should you need it.

Live Demo

Dashboard

Issues, Contributions, or Requests

Feature(s) missing? Something broken?
Post your questions, comments, and issues right here in this GitHub repository. We welcome any input you may have and will happily respond promptly. And feel free to fork this repo to append any additional features you like.

Thank you for reading this tutorial.
Happy PHP Charting with ZingChart