IPU-Chart for WordPress User Guide

Version: 0.8

You can try and modify the examples of this user guide with the IPU-Chart Editor.

Content

  1. Introduction
  2. Download & Installation
  3. Quick Start
  4. IPU-Chart Editor
  5. Attributes of the chart shortcode
  6. Styling charts with CSS
  7. Working with JSON
  8. Cross-Origin Resource Sharing (CORS)
  9. Usage Examples

Introduction

This user guide describes the usage of the IPU-Chart plugin for WordPress in depth. It explains the different attributes the shortcodes have, the css styles of a chart and gives some working code examples for each type of chart.

You can also try the examples in the IPU-Chart Editor. This tools lets you define the data and shortcode in an easier, structured way.

Visit the Product Home Page for an overview to the IPU-Chart WordPress plugin. Our regular Blogs about IPU-Chart discuss different aspects of the plugin.

If you have questions or suggestions please visit the Support Forums.

Download & Installation

  1. Login or Register (optional).
  2. Download the latest version from the WordPress plugins directory.
  3. Install the plugin in your WordPress environment.

Download and Installation of IPU-Chart Multi Series

  1. Login or Register.
  2. Purchase your license key for IPU-Chart Multi Series for WordPress.
  3. Download and install the plugin.
  4. Enter the license key in the configuration panel of IPU-Chart
  5. Press ‘Save Changes’ to save your license key.
  6. Activate the license key (button will show up after you saved the key).
Enter your license key, save it and then activate it in the IPU-Chart settings.

Enter your license key, save it and then activate it in the IPU-Chart settings.

After you purchases you will receive a mail with the download link and the license key. You can download the software and find the license keys your purchased after under the menu item Account > Purchase History.

Quick Start

Enter your csv data in your WordPress post or page. Example:

[csv id="data"]Country,Population
       China,1343.24
       India,1205.07
       USA,313.85
       Indonesia,248.22
       Brazil,205.72[/csv]

To define the chart refer to the csv or tsv id with a chart short code. Important: Please enter the attributes in one line without the linefeeds (otherwise WordPress will not understand the shortcode). The linefeeds in the example are for legibility only.

[chart csv="#data" 
       type="bar"
       category="Country"
       value="Population"
       format="string,number"
       color="auto"
       title="Top five most populous countries of the world..."
       description="The top five most populous countries of the world..."
       sort="Population"
       style="width:600px; height:400px;"
       animate="medium"
       img="https://www.ipublia.com/wp-content/uploads/chart-x1.png"
       debug="false"]

This displays a bar chart:

To display a donut chart just change the type attribute to ‘donut’:

[chart csv="#data" 
       type="donut"
       category="Country"
       value="Population"
       format="string,number"
       color="auto"
       title="Top five most populous countries of the world..."
       description="The top five most populous countries of the world..."
       sort="Population"
       animate="medium"
       img="https://www.ipublia.com/wp-content/uploads/chart-x1.png"
       debug="false"]

This displays a donut chart:

To insert a table view of the csv or tsv:

[chart type="table"
       csv="#data"
       category='Country'
       value='Population'
       format='string, number'
       title="Top five most populous countries of the world..."]

This renders the following table:

That’s it!

IPU-Chart Editor

The IPU-Chart Editor lets you define the data and shortcode in an easier, structured way. When the work is done just copy & paste the generated shortcode(s) to your blog or page. There are three steps to define your chart:

  1. Define the data for the chart. You can enter the data enter in the panel or reference it by an url.
  2. Define the chart’s attributes like it’s type (bar, pie, donut, line, scatter, world map, bubble), category, value(s), formats and colors.
  3. Preview the chart (press the refresh button) and copy the shortcodes generated by the editor to your blog or page.

Attributes of the chart shortcode

Attibute Description
id The id of the chart (optional, default is a system generated id).
csv A reference to a csv formatted data entity.
This can be the id of csv shortcode or an uri that points to a csv formatted file.
tsv A reference to a tsv formatted data entity.
This can be the id of tsv shortcode or an uri that points to a tsv formatted file.
json A reference to a json formatted data entity.
This can be the id of json shortcode or an uri that points to a json formatted file.
adapter A javascript expression.
A javascript expression that transforms the data to display into an array of objects.
Default: return data;
type The type of chart that must be rendered.
bar|bar.horizontal|pie|donut|line|scatter|bubble|map.world.countries
Multi Series Extension: bar.ms.animated
category The column name of the csv that represents the category of the chart. Case-sensitiv!
value The column name of the csv that represents the value of the chart. Case-sensitiv!
format The format of the data in the csv. Comma-separated, category first, value second.
string|s for a string
number|n for number (integer or float)
integer|i for an integer
float|f for a floating point number
date|d for dates like 2013-12-31
yyyy-mm-dd|yy-mm-dd|yyyy/mm/dd|yy/mm/dd|dd.mm.yyyy|dd.mm.yy for other date formats
color The color of each category (optional, default is auto).
A list of colors, or ‘auto’. Colors repeat if there aren’t enough.
style A CSS style for the html figure element (optional).
title The title of the chart rendered as a figcaption.
description The description of the chart included in the SVG. Do it for search engines!
sort Sorting of the data
true|false default: false. (For bubble charts only at the moment!)
interpolate The interpolation for line charts
linear piecewise linear segments
basis a B-spline, with control point duplication on the ends
cardinal a Cardinal spline, with control point duplication on the ends
monotone cubic interpolation that preserves monotonicity in y.

For more information see SVG Paths and D3.js

animate The animation (experimental, for bar charts only)
slow The duration for each category is 5 seconds
medium The duration for each category is 2 seconds
fast The duration for each category is 1 second

To start an animation click or tap on the chart.

img The url of an alternative image for older browsers that do not support SVG.
Usually a screenshot of the chart.
debug Print debug information to the browser console (optional, default is false).
true|false

Styling Chars with CSS

The styling of any chart type can be done precisely and fast with IPU-Chart. There are only a few css rules you need to know and you will easily style your charts the way you like it.

The plugin has a default stylesheet included. It renders a line chart more or less like shown with the examples on this site.

Consider the use of a WordPress child theme

You can change the stylesheet in the plugin directory of IPU-Chart. But this isn’t the recommended way as the update mechanism will overwrite the files in the plugin directory with every update.

You can also define the styles in the blog or page itself with the style tag. This sets the styles only for the charts that are on this page (which can be an advantage in some cases). But as said, the best place is the style.css of a child theme.

If not already done you should create a child theme and change the css there. To do so create a subfolder in your WordPress theme directory (example: /wordpress/wp-content/themes/twentytwelve-child) and add a file called style.css with the following header to the new directory:

/*
Theme Name:     Twenty Twelve Child
Theme URI:      http://yourdomain.com/wordpress/
Description:    Child theme for Twenty Twelve
Author:         Donald Duck
Author URI:     http://yourdomain.com/author
Template:       twentytwelve
Version:        1.0
*/

@import url("../twentytwelve/style.css");

You can now activate the new child theme in the appearance settings of WordPress. Afterwards you can add styles for your charts (and any other WordPress page) to this file (and it will never be overwritten by an update). The WordPress Codex contains more information about child themes.

The Elements of a Chart

All charts created with IPU-Chart are embedded in a HTML figure element with a figure caption (figcaption) and the svg element that contains the chart itself. The picture below shows this basic element structure of IPU-Chart.

The basic elements of a chart. Red the 'figure', green the 'figcaption' and blue the 'svg' element.

The basic elements of a chart. Red the ‘figure’, green the ‘figcaption’ and blue the ‘svg’ element.

You can add styles to your charts in two ways:

  1. For all charts of all posts and pages
  2. For only a specific chart

If you want style a specific chart just add an id to your [chart] shortcode and set the rule to the context of this id.

CSS Selectors

CSS Selector Description Example Rule
figure.chart All figures with a chart figure.chart { background: lightgray; }
.chart figcaption All figure captions .chart figcaption { font-size: 1.2em; font-weight: bold; }
.chart svg The svg element .chart svg { background: black; }
.chart svg The svg element .chart svg { background: black; }
.x.axis * line The grid for the x-axis .x.axis * line { stroke: none; }
.y.axis * line The grid for the y-axis .y.axis * line { stroke-dasharray: 9,3; }
.x.label The label of the x-axis .x.label { font-size: 1.2em; font-weight: bold; }
.y.label The label of the y-axis .y.label { font-size: 1.2em; font-weight: bold; }
.x.axis * text The text/numbers/dates on the x-axis .x.axis * text { font-size: 0.7em; fill: white; }
.y.axis * text The text/numbers/dates on the y-axis .y.axis * text { font-size: 0.7em; fill: white; }
.chart * .line The curve of a line chart .chart * .line { stroke-width: 4px; }

See the post How To Style a Line Chart in WordPress for an example and step by step introduction to styles.

Working with JSON

You can of course access json data by uri. But if preferred you can also put json formatted data inside a post or page – like it can be done with csv and tsv. Just use the [json] shortcode for this and reference it with the json attribute of the chart shortcode.

Writing a Data Adapter

IPU-Chart expects a (flat) array of objects as input data. The category and value definitions must be attributes of these objects.
In the case of tsv or csv we load always an array of objects. In the case of json input the data is often structured hierarchically. The job of the data adapter is to transform this hierarchy to a flat array.

The data adapter can be any javascript function (plain js, jQuery or d3) that returns an array of objects. The function has as only argument the data object returned by the json call.
Of course the adapter can also do more work. It could for example merge different parts of the response, calculate new values or change the attribute names.

JSON Example

We can reformulate our population example with json like this: Enter the following json shortcode in your blog or page:

[json id='d25307']
{
  "results": {
    "country": [
      {
        "ISO-3166-1": "156",
        "Name": "China",
        "Population (mio)": "1349.59",
        "Median age (years)": "36.3"
      },
      {
        "ISO-3166-1": "356",
        "Name": "India",
        "Population (mio)": "1220.80",
        "Median age (years)": "26.7"
      },
      {
        "ISO-3166-1": "840",
        "Name": "USA",
        "Population (mio)": "316.67",
        "Median age (years)": "37.2"
      }
    ]
  }
}
[/json]

Reference the json data with a [chart] shortcode as following:

[chart id="c25307" json="#d25307" adapter="return data.results.country;" type="bubble" category="Name" value="Population (mio),Median age (years)" format="s,n,n,n" color="auto" style="width:100%;height:400px;" title="Statistical aspects of the top three most populous countries of the world. Source: World Factbook, July 2013 est." description="Set a description..." sort="false" interpolate="none" img="" debug="true"]

The adapter returns the array of countries (return data.results.country;) which resides in the results branch of the json.

For an example that shows the binding of a live json feed have a look at the post JSON Chart Example with Yahoo YQL.

Cross-Origin Resource Sharing (CORS)

If you load the data to display with IPU-Chart from a server you must allow cross-origin requests. Otherwise the data cannot be accessed by the browsers that are not on the same domain as the server.

To allow browsers to load data cross origin (CORS) add the following statements to the .htaccess file of your server’s dowload directory:

Header set Access-Control-Allow-Origin "*"
Header set Access-Control-Allow-Headers "origin, x-requested-with, content-type"
Header set Access-Control-Allow-Methods "GET, OPTIONS"

For more information about CORS see the W3C CORS Specification.

Further Reading

Leave a Reply