Peity - Documentation

What is Peity?

Peity is a minimalist jQuery plugin that allows you to create small, inline charts within your web pages. It’s designed for creating simple, visually appealing charts without the overhead of large JavaScript libraries like Chart.js or D3.js. Peity excels at providing quick, easily-integrated data visualizations directly within the text flow of your webpage. It supports several chart types, including line charts, bar charts, and pie charts, making it versatile for various data representation needs.

Why use Peity?

Peity’s strengths lie in its simplicity and ease of use. Here are some key reasons to choose it:

Setting up Peity: Installation and Inclusion

Peity is readily available via a CDN or you can download it directly. The simplest method is to include it via a CDN link in your HTML file’s <head> section:

<script src="https://cdn.jsdelivr.net/npm/peity"></script>

Alternatively, download the jquery.peity.min.js file and include it locally:

<script src="path/to/jquery.peity.min.js"></script>

Remember that Peity requires jQuery. Ensure you’ve included jQuery before including the Peity script. For example:

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/peity"></script>

Basic Usage Example

Peity’s core functionality is extremely simple. You create a chart by selecting an HTML element containing your data and calling the .peity() method. The data is typically provided as a space-separated string of numbers.

<span class="peity-line" data-peity='{ "fill": ["#008000"], "stroke": "#008000" }'>1 2 3 4 5 2 1</span>

<script>
  $('.peity-line').peity('line');
</script>

This code snippet creates a simple line chart. The data-peity attribute allows for optional configuration options (in JSON format), in this case we’ve specified fill and stroke color. The JavaScript code then initializes the chart using the appropriate Peity method (line in this example). Other chart types like bar, pie, etc., can be used similarly, by replacing "line" with the desired type. More advanced usage and options are detailed in the following sections.

Chart Types

Line Charts

Line charts in Peity display data as a connected series of points, ideal for showing trends over time or illustrating relationships between data points.

Basic Usage:

<span class="line-chart">5,3,9,6,5,9,7,3,5,2</span>
<script>
  $('.line-chart').peity('line');
</script>

This creates a basic line chart. Data values are comma-separated.

Options:

Bar Charts

Bar charts in Peity represent data as a series of vertical bars, useful for comparing the values of different categories.

Basic Usage:

<span class="bar-chart">5,3,9,6,5,9,7,3,5,2</span>
<script>
  $('.bar-chart').peity('bar');
</script>

This creates a basic bar chart.

Options:

Pie Charts

Pie charts in Peity display data as proportional slices of a circle, showing the relative contribution of each part to a whole.

Basic Usage:

<span class="pie-chart">1,2,3,4</span>
<script>
  $('.pie-chart').peity('pie');
</script>

This creates a basic pie chart.

Options:

Donut Charts

Donut charts are similar to pie charts but with a hole in the center, often used to emphasize the proportion rather than the absolute values. Donut charts are created using the pie chart type with the innerRadius option.

Basic Usage:

<span class="donut-chart">1,5,9,3</span>
<script>
  $('.donut-chart').peity('pie', {innerRadius: .5});
</script>

This creates a donut chart with a 50% inner radius. Adjust the innerRadius value (between 0 and 1) to control the size of the hole. All other options for pie charts apply to donut charts as well.

Data Handling

Data Formats: Arrays and Objects

Peity primarily accepts data in two formats: space-separated strings and arrays/objects.

Space-separated strings: This is the simplest format, where numerical data values are separated by spaces within the HTML element’s text content. This is the method shown in most basic examples.

<span>1 2 3 4 5</span>

Arrays/Objects: For more complex scenarios or when using options that require associating data points with additional attributes (e.g., labels or colors), you can provide data as a JavaScript array or object within the data option of the peity function.

$('.my-chart').peity('line', {
    data: [1, 2, 3, 4, 5],
    //other options here...
});

Or using an object:

$('.my-chart').peity('bar', {
    data: [{ value: 1, label: 'A'}, {value: 2, label: 'B'}, {value: 3, label: 'C'}],
    //other options here...
});

Note that when using an object, you must specify a value property for the numerical data. Peity will currently ignore other properties, although future versions may leverage this for additional features.

Data Attributes

Peity primarily utilizes the data-peity attribute for specifying options. This attribute should contain a JSON object defining the chart’s configuration:

<span data-peity='{"fill": ["#f00", "#0f0"], "stroke": "#00f"}'>1 2 3 4 5</span>

This will create a line chart with red and green fills and a blue stroke. Note that options set within the data-peity attribute will override options set in the javascript call.

Handling Large Datasets

Peity is not optimized for extremely large datasets. For very large amounts of data, consider using a more robust charting library like Chart.js or D3.js, which are designed for performance with many data points. Peity’s intended use is for smaller, inline charts where ease of use and minimal code are prioritized over handling massive datasets.

Data Updates and Redrawing

To update the data in a Peity chart, you must destroy the existing chart and then re-create it with the new data. Peity doesn’t offer a built-in method for updating data in place.

let myChart = $('.my-chart');
myChart.peity('destroy');  //remove existing chart

let newData = [6, 7, 8, 9, 10];
myChart.peity('line', {data: newData}); //recreate chart with new data

This ensures that the chart is correctly redrawn with the updated values. Remember to replace 'line' with the appropriate chart type.

Customization Options

Width and Height

You can control the width and height of Peity charts using the width and height options. These options accept numerical values (e.g., width: 100, height: 50) representing pixels. You can also specify these values as percentages or other valid CSS units, but this is less common. These are passed either via the data-peity attribute or as part of the options object when calling .peity().

$('.my-chart').peity('line', { width: 200, height: 100 });

or

<span data-peity='{ "width": 150, "height": 60 }'>1,2,3,4,5</span>

Colors and Fill Styles

Colors are primarily controlled using the fill option. For line charts, fill can be a boolean (true for filling the area under the line, false otherwise), a single color string (e.g., “#ff0000” or “red”), or an array of color strings for gradient fills. For bar and pie charts, fill is an array of colors, one for each bar or slice.

$('.my-chart').peity('bar', { fill: ['#008000', '#000080', '#800000'] });

Stroke Styles

The appearance of lines in line charts is controlled by the stroke and strokeWidth options. stroke sets the line color (similar to fill), and strokeWidth sets its thickness in pixels.

$('.my-chart').peity('line', { stroke: '#0000FF', strokeWidth: 3 });

Gridlines and Markers

Peity doesn’t directly support gridlines or markers. This is a deliberate design choice to maintain its minimalist nature. To achieve this functionality, you will likely need to utilize CSS or another charting library.

Labels and Legends

Peity doesn’t have built-in support for labels or legends. To add labels, you’ll need to add them manually within your HTML alongside the charts. For more advanced legend features, you would need to use another library.

Tooltips and Interactive Elements

Peity itself does not provide tooltips or other interactive elements. To add interactivity (hover effects, tooltips, etc.), you’ll need to use separate JavaScript libraries or write custom JavaScript code that interacts with the chart elements.

Customizing the Appearance of Different Chart Types

Customization options often vary slightly depending on the chart type. For example, the innerRadius option is specific to donut charts (a type of pie chart). Consult the individual chart type descriptions (above) for their specific customization options. Refer to the complete list of options available within the Peity source code for a comprehensive overview. Remember, that many advanced customization needs are better suited to more feature-rich libraries. Peity’s power is in its simplicity and ease of integration.

Advanced Techniques

Using Peity with Frameworks (React, Angular, Vue)

Peity is a jQuery plugin, so its direct integration with modern JavaScript frameworks like React, Angular, and Vue requires a bit of care. The simplest approach involves using Peity within a lifecycle method (e.g., componentDidMount in React, ngOnInit in Angular) after the DOM element has been rendered.

React Example:

import React, { useEffect, useRef } from 'react';
import $ from 'jquery';
import 'peity'; //Import peity

function MyComponent() {
  const chartRef = useRef(null);

  useEffect(() => {
    if (chartRef.current) {
      $(chartRef.current).peity('line');
    }
  }, []);

  return (
    <div>
      <span ref={chartRef}>5,3,9,6,5,9,7,3,5,2</span>
    </div>
  );
}
export default MyComponent;

Remember to include jQuery and Peity in your project, and adjust the code according to your chosen framework’s component lifecycle. For larger applications consider a wrapper component to manage chart creation and updates more cleanly.

Creating Custom Chart Types

Peity doesn’t directly support creating custom chart types. Its core functionality is limited to the predefined types. To create a completely new chart type, you would need to write a separate JavaScript plugin or use a different charting library.

Integrating with Other Libraries

Peity can be used alongside other JavaScript libraries, but careful consideration is needed to avoid conflicts. Ensure that all libraries are included correctly and that there are no naming conflicts or dependencies that could cause issues. Generally, if the other libraries don’t directly manipulate the DOM elements used by Peity, integration should be straightforward.

Performance Optimization

For optimal performance with Peity:

Troubleshooting

Common Errors and Solutions

Debugging Tips

Browser Compatibility

Peity generally works well in modern browsers. However, very old or outdated browsers might not support all its features or may have rendering issues. Peity is designed to work with jQuery, so browser compatibility is also subject to the limits of the jQuery library. For best results, support only widely-used, modern browsers.

Known Issues

API Reference

Options Reference

Peity options are passed as a JSON object either through the data-peity attribute or as the second argument to the .peity() method. Many options are applicable across multiple chart types, but some are specific to certain chart types. Options set in the data-peity attribute will override those passed to .peity().

Common Options:

Pie Chart Specific Options:

Refer to the previous sections (“Chart Types” and “Customization Options”) for more detailed explanations of these options and chart-specific options.

Methods Reference

There are no other public methods directly exposed by the Peity plugin. Additional functionality needs to be implemented via custom JavaScript.

Events Reference

Peity does not trigger any custom events. To add interactivity, you’ll need to use standard DOM events (like mouseover, mouseout, click) on the chart’s container element and handle them in your own JavaScript code. Note that the chart element’s contents are typically generated dynamically by Peity; it’s usually better to handle events on the parent element rather than directly on the dynamically generated elements.