Zend Framework: Zend_Service_Gchart Component Proposal

Proposed Component Name	Zend_Service_Gchart
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_Gchart
Proposers	Jeremy Giberson
Zend Liaison	TBD
Revision	1.0 - 1 January 2008: Initial Draft. (wiki revision: 6)

This component will provide chart type independent object instances.
Each object instance of this component will accept every GChart option.
The object will determine what options to accept and send with GChart API Request.
This component will provide minimal error checking.
This component may support using POST request to GChart's Api service to avoid natural url size limit of GET requests. This depends on Gcharts support of POST requests.

4. Dependencies on Other Framework Components

Zend_Cache
Zend_Exception
Zend_Service

5. Theory of Operation

You may statically configure a Zend_Cache object for Gchart. If so, you must specify a valid directory with write access for image generation.

The component is instantiated using Zend_Service_Chart with out any fore-knowledge of the chart type.
At minimum you will provide the gchart instance with a Zend_Service_Gchart_Parameter_Data object, and a Zend_Service_Gchart_Parameter_Size object.
You can add a single instance of any|all other Zend_Service_Gchart_Parameter_ objects.
To generate the image url you will specify the type of gchart using one of the provided Zend_Service_Gchart::CHART_TYPE_ constant values.
If you have configured Zend_Service_Gchart for cache, during request url generation it will check the cache for pre-existing gchart api response. If a previous response exists, it will use the raw image data to create a temporary image file in the specified image directory, and return the url to this file. If data does not exist in the cache for the request a new request will be sent to Gchart API using GET|POST and the raw image data from the response will be saved in the cache.
If cache has not been configured for Zend_Service_Gchart, then a gchart request uri will be constructed and returned.

How request parameters are generated:
Each parameter of the instance will be iterated through and asked if compatible with the chart type specified for the request.
If the the parameter is compatible it will be asked for an array of $key=>$value pairs to be included in the request.
The request is serialized using the google chart api URI and request pairs.
You will use the uri as the image source like so:
<img src='$request_uri'/>

6. Milestones / Tasks

Milestone 1: [DONE] Class layout will be developed to facilitate the goals of this component
Milestone 2: Support for all current chart options will be completed
Milestone 3: Integrate Zend_Cache support for saving requests
Milestone 4: Component is reviewed and accepted for the Zend Framework Incubator
Milestone 5: Working prototype checked into incubator svn
Milestone 6: Initial documentation exists

7. Class Index

[DONE]

Zend_Service_Gchart
Zend_Service_Gchart_Parameter_Interface
Zend_Service_Gchart_Parameter_Colors
Zend_Service_Gchart_Parameter_Data_Interface
Zend_Service_Gchart_Parameter_Data_Abstract
Zend_Service_Gchart_Parameter_Data_Extended
Zend_Service_Gchart_Parameter_Data_Simple
Zend_Service_Gchart_Parameter_Data_Text
Zend_Service_Gchart_Parameter_Legend
Zend_Service_Gchart_Parameter_PieLabels
Zend_Service_Gchart_Parameter_Size
Zend_Service_Gchart_Parameter_Title
[TODO]
Zend_Service_Gchart_Parameter_* (remaining gchart options)

8. Use Cases

UC-01

$gc = new Zend_Service_Gchart();

// size
$size = new Zend_Service_Gchart_Parameter_Size('320', '200');

// data
$data = new Zend_Service_Gchart_Parameter_Data_Text();
$sid = $data->addDataSeries(array(20, 22, 15, 45, 10));
$sid2 = $data->addDataSeries(array(21, 11, 24, 10, 55));
$data->setScaled(true);

// title
$title = new Zend_Service_Gchart_Parameter_Title("Performance Comparison\nAwesomeness vs. Uberness");

// legend
$legend = new Zend_Service_Gchart_Parameter_Legend($data);
$legend->setDataLabel($sid, 'Awesomeness');
$legend->setDataLabel($sid2, 'Uberness');
$legend->setPosition( Zend_Service_Gchart_Parameter_Legend::LEGEND_POSITION_BOTTOM );

// colors
$colors = new Zend_Service_Gchart_Parameter_Colors($data);
$colors->setSeriesColor($sid2, '0000ff');
$colors->addColors(array('ff0000', '00ff00', 'ffff00', '00ffff'));

// required parameters
$gc->setData($data);
$gc->setSize($size);

// optional parameters
$gc->addParameter($legend);
$gc->addParameter($colors);
$gc->addParameter($title);
// view usage
 
<img src='<?=$this->gc->getImageUrl(Zend_Service_Gchart::CHART_TYPE_PIE);?>'>
 
<img src='<?=$this->gc->getImageUrl(Zend_Service_Gchart::CHART_TYPE_PIE_3D);?>'>
 
<img src='<?=$this->gc->getImageUrl(Zend_Service_Gchart::CHART_TYPE_LINE_SPARK);?>'>
 
<img src='<?=$this->gc->getImageUrl(Zend_Service_Gchart::CHART_TYPE_BAR_HORIZONTAL_GROUPED);?>'>
 
<img src='<?=$this->gc->getImageUrl(Zend_Service_Gchart::CHART_TYPE_SCATTER_PLOT);?>'>

// OUTPUT:

// NOTE
You'll notice the pie charts only exhibit one data series. Since Pie charts only expect one series, it ignores other series in the data set.
I'm thinking it might be nice to be able to set a primary series with a data set that way you can specify which series (of many) is chosen for chart types that only support one series. This way, you can pack all your data into a single chart object, and in the view switch primary series and render charts for the series. Or render bar, line, etc using all the data.

9. Class Skeletons

These are the current skeletons for the GChart, Parameter Interface, and Parameter_Data. Please see the attached source for more classes and full function definitions. Each class has documentation in it.

Name Size Creator (Last Modifier) Creation Date Last Mod Date Comment

Zend.zip 10 kb Jeremy Giberson Jul 15, 2008 Jul 15, 2008 Current Source of component

<?php
	require_once 'Zend/Service/Abstract.php';

	class Zend_Service_Gchart extends Zend_Service_Abstract {
		/**
		 *  Chart API URI
		 */
		const API_URI = 'http://chart.apis.google.com/chart';

		/**
		 * Chart Types
		 */
		const CHART_TYPE_LINE = 'lc';
		const CHART_TYPE_LINE_PAIRED = 'lxy';
		const CHART_TYPE_LINE_SPARK = 'ls';
		const CHART_TYPE_BAR_HORIZONTAL_STACKED = 'bhs';
		const CHART_TYPE_BAR_VERTICAL_STACKED = 'bvs';
		const CHART_TYPE_BAR_HORIZONTAL_GROUPED = 'bhg';
		const CHART_TYPE_BAR_VERTICAL_GROUPED = 'bvg';
		const CHART_TYPE_PIE = 'p';
		const CHART_TYPE_PIE_3D = 'p3';
		const CHART_TYPE_VENN_DIAGRAM = 'v';
		const CHART_TYPE_SCATTER_PLOT = 's';
		const CHART_TYPE_RADAR_LINE = 'r';
		const CHART_TYPE_RADAR_SPLINE = 'rs';
		const CHART_TYPE_MAP = 't';
		const CHART_TYPE_GOOGLE_O_METER = 'gom';
		const CHART_TYPE_QR_CODES = 'qr';
		
		/**
		 * Reference to REST client object
		 */
		protected $_restClient = null;
		
		/**
		 * Contains parameters for the google chart
		 *
		 * @var Zend_Service_Gchart_Parameter_Interface[]
		 */
		protected $parameters = array();
		
		/**
		 * Reference to the data set the chart will render
		 *
		 * @var Zend_Service_Gchart_Data_Interface
		 */
		protected $data = null;
		
		/**
		 * Reference to the chart size
		 *
		 * @var unknown_type
		 */
		protected $size = null;
		
		public function __construct() {	}
		

		/**
		 * Set the data for the chart to render.
		 *
		 * @param Zend_Service_Gchart_Data_Interface $data
		 */
		public function setData(Zend_Service_Gchart_Parameter_Data_Interface $data) {}
		
		public function setSize(Zend_Service_Gchart_Parameter_Size $size) {}
		
		/**
		 * Add chart option parameter to this chart.
		 *
		 * @param Zend_Service_Gchart_Parameter_Interface $p
		 */
		public function addParameter(Zend_Service_Gchart_Parameter_Interface $p) {}
		
	    /**
	     * Returns a reference to the REST client, instantiating it if necessary
	     *
	     * @return Zend_Rest_Client
	     */
	    public function getRestClient(){}

	    /**
	     * Get the request string that would be used for a request to google api
	     *
	     * @param string $chartType
	     * @return string
	     */
		public function getRequestString($chartType) {}

		
		/**
		 * This code generates the <img> src used to diplay the chart.
		 * Because we use support cache, this might not reference google chart uri
		 * but rather a local file!
		 *
		 * @param string chartType
		 * @return string
		 */
		public function getImageUrl($chartType) {}
	}

/**
	 * Interface for GChart parameters
	 *
	 */
	interface Zend_Service_Gchart_Parameter_Interface {
		
		/**
		 * Check if parameter is compatible with given chart type
		 *
		 * @param string $chartType
		 * @return boolean
		 */
		public function isCompatibleWithChart($chartType);
		
		/**
		 * Return array pair(s) of request variable name and value
		 *
		 * @return array
		 */
		public function toRequestPairs();
	}

<?php


	interface Zend_Service_Gchart_Parameter_Data_Interface {
		
		/**
		 * Add new series to the data, returns a hash id to the series.
		 *
		 * @param array $data_points
		 * @return string id
		 */
		public function addDataSeries(Array $data_points = array());
		
		/**
		 * Add data points to the current data points in $series
		 *
		 * @param unknown_type $series
		 * @param array $data_point
		 */
		public function addDataPoints($series, Array $data_points);
		
		/**
		 * Return the series array
		 *
		 * @return array
		 */
		public function getDataSeries();
		
		/**
		 * Return data points for a specified series
		 *
		 * @param string $seriesId
		 * @return array
		 */
		public function getDataPoints($seriesId);
		
		/**
		 * Check if seriesId exist in this data set
		 *
		 * @param string $seriesId
		 * @return boolean;
		 */
		public function isSeriesId($seriesId);
		
		/**
		 * Remove series from data specified by id
		 *
		 * @param string $id
		 */
		public function removeDataSeries($id);
	}

/**
	 * Google Chart Required Parameter: Chart Data
	 * 
	 *
	 */
	abstract class Zend_Service_Gchart_Parameter_Data_Abstract implements Zend_Service_Gchart_Parameter_Interface {
		protected $_data = array();
		
		/**
		 * Add new series to the data, returns a hash id to the series.
		 *
		 * @param array $data_points
		 * @return string id
		 */
		public function addDataSeries(Array $data_points = array()) {}
		
		/**
		 * Add data points to the current data points in $series
		 *
		 * @param unknown_type $series
		 * @param array $data_point
		 */
		public function addDataPoints($series, Array $data_points) {}
		
		/**
		 * Return the series array
		 *
		 * @return array
		 */
		public function getDataSeries() {}
		
		/**
		 * Return data points for a specified series
		 *
		 * @param string $seriesId
		 * @return array
		 */
		public function getDataPoints($seriesId) {}
		
		/**
		 * Check if seriesId exist in this data set
		 *
		 * @param string $seriesId
		 * @return boolean;
		 */
		public function isSeriesId($seriesId) {	}
		
		/**
		 * Remove series from data specified by id
		 *
		 * @param string $id
		 */
		public function removeDataSeries($id) {	}
		
		
		/**
		 * Check if parameter is compatible with given chart type
		 *
		 * @param string $chartType
		 * @return boolean
		 */
		public function isCompatibleWithChart($chartType) {}
		
	}

If you are wondering why there is an interface class and abstract class for data, it is because the abstract class has several functions implemented that wont change between data subclasses and the sub classes need to be interfaces to require the provide correct accessors.

Page Operations

Browse Space

Zend_Service_Gchart-Alt

Labels

Zend Framework: Zend_Service_Gchart Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria