{% extends "layouts/master.html" %} {% set current_page = 'docs' %} {% block title %}{% parent %} ยป Documentation{% endblock %} {% import "macros.html" as docMacro %} {% block page_content %}

Documentation

Quick Start

Download D3.js

Download and include D3.js on your page.

Download xCharts

Download and include xcharts.js and xcharts.css on your page.

Configure Your Data

Configure your data using xChart's Data Format.

Set Up Your Page

Add an element with a defined width and height to your page to display your chart:

<figure style="width: 400px; height: 300px;" id="myChart"></figure>

xCharts will fit to the given element's width and height. It's important to have these values set on the element or in a stylesheet. On window resize, if the element resizes, xCharts will resize accordingly, so that it can continue to fit in the allotted space.

Create Your Chart

var myChart = new xChart('bar', data, '#myChart');

Data Format

xCharts uses its input data to instruct it on how the dataset should be drawn. By providing the following data, an xChart will be instructed to draw an ordinal bar chart with a linear scale, containing two ordinal ticks on the x-axis for "Pepperoni" and "Cheese". There will also be a secondary dotted-line component overlayed on top of the bars.

Example Data

{{ pizza|json_encode(2) }}
{% for data in dataFormat %}

{{ loop.key }} {% if data.optional %}optional{% endif %}

{{ docMacro.vars(data) }}
{% endfor %}

Methods

{% for method in methods %}

{{ loop.key }}({% for arg in method.arguments %}{{ loop.key }}{% if not loop.last %}, {% endif %}{% endfor %})

{{ method.desc|raw }}

{% for arg in method.arguments %}
{{ loop.key }}
{{ docMacro.vars(arg) }}
{% endfor %}
{% endfor %}

Chart Options

{% for opt in defaults %}

{{ loop.key }}

{{ docMacro.vars(opt) }}
{% endfor %}

Custom Scales

By default, xCharts includes four scale types: ordinal, linear, time, and exponential. However, you can create custom scale types very easily.

function myScale(data, axis, bounds, extents) {
  return d3.scale.linear()
    .domain(extents)
    .nice()
    .rangeRound(bounds);
}
xChart.setScale('scale-name', myScale);

Arguments

data
object
Merged set of all data that will be displayed on the chart.
axis
string
Either x or y.
bounds
array
Min and max screen position values for the given axis.
extents
array
Min and max values for the data.

Styling Your Chart

Since xCharts (and D3.js) use SVG, we are able to accomplish most of our styling of xCharts directly through CSS. This means that, unlike many other charting libraries, you have quite a bit of control to handle the visualization however you want.

The best way to style charts is to start with the included stylesheet, or use your browser's element inspector to see each elements CSS class selectors that are available to use.

Series Colors

Each series in the chart is assigned a class, based on its index in your main and comp data sets: .color0 through .colorN. While there can be an infinite amount of colors, it is recommended that you never chart more than 10 series at a time. Thus, only 10 colors are included in the starter stylesheet.


Custom Vis Types

xCharts follows the "Enter, Update, Exit" methodology of D3.js. If you're unfamiliary with D3, a good starting reference point is Thinking With Joins.

To create your own vis type and make it available to xCharts, simply create an object of the necessary methods and define it for xCharts using the xChart.setVis(name, methods); method.

var myVis = {
{%- for method in vismethods %}
  {{ loop.key }}: function () { /*...*/ }{% if not loop.last %},{% endif %} {% if method.optional %}// optional{% endif %}
{%- endfor %}
};
xChart.setVis('myvis', MyVis);

Extending Base Vis Types

It can be useful, at times, to extend a base vis type. For example, if you'd like to create a vis type that uses logic from the line vis type, simply ask xChart for the methods and reuse them:

var line = xChart.getVis('line');
var myVis = {
  enter: function (self, storage, className, data) {
    line.enter.apply(this, arguments);
    // Do your custom actions here
  },
  update: function (self, storage, timing) {
    line.update.apply(this, arguments);
    // Do your custom actions here
  },
  exit: function (self, storage, timing) {
    line.exit.apply(this, arguments);
    // Do your custom actions here
  },
  destroy: function (self, storage, timing) {
    line.destroy.apply(this, arguments);
    // Do your custom actions here
  },
};
xChart.setVis('myvis', myVis);

For a more detailed and working example, check out the Error Bars Custom Vis Type.

Methods

{% for method in vismethods %}

{{ loop.key }}({% for arg in method.arguments %}{{ loop.key }}{% if not loop.last %}, {% endif %}{% endfor %})

{% if method.optional %}Optional. {% endif %}{{ method.desc|raw }}

{% for arg in method.arguments %}
{{ loop.key }}
{{ arg }}
{% endfor %}
{% if method.inc %} {% include method.inc ignore missing %} {% endif %}
{% endfor %}

{% endblock %} {% block js %} {% endblock %}