[[PageOutline(2-5,Contents,pullout)]]

= Create bar/line/pie charts of query results

{{{#!box info
'''Notice''': The plugin is at its very infancy (May 2018) so only a fraction of plotly's functionality is supported, parameter syntax may change a bit and error checking is very likely to be improveable.
}}}

{{{#!box warning
'''Notice''': Enabling this plugin completely breaks almost all security barriers as a result of full database access.
}}}

== Description

This macro allows you to create a bar/line/pie chart of a SQL query output using the [https://plot.ly/javascript/ plotly.js] JavaScript plotting engine in your Trac wiki pages and ticket pages. Plotly itself is MIT licensed.

The plugin egg contains plotly.js, ie there are no external web references.

A given wiki page can contain any number of plots.

Enter the following in your wiki page:

{{{
[[yachart(id=first; title=Action statuses; query=SELECT status, COUNT(status) FROM ticket WHERE type = 'Action' GROUP BY status)]]
}}}

This will result in something like this:

[[Image(newplot(1).png, border=2, width=500)]]

Note the use of semicolon (;) as the delimiter character for the macro arguments. This is chosen to avoid ambiguity with commas which are common in SQL queries.

The query must return two columns. In `line` and `bar` charts, the first column will be used as x-axis data and the second column as y-axis data. In `pie` charts, the columns will be used as labels and values, respectively.

In the query, the macro will replace the string `$USER` with the id of the user logged in. This can be used to display "my tickets":

[[Image(newplot(2).png, border=2, width=500)]]

WikiProcessor syntax is supported which may make queries easier to read and write:
{{{
{{{#!yachart
   id=something;
   title=something else;
   query=SELECT status, COUNT(status) 
         FROM ticket 
         WHERE type = 'Action' 
         GROUP BY status;
}}}
}}}

=== Parameters

{{{#!ini
id            = dom-name     # The name of the HTML DOM carrying the chart. Mandatory. Must be unique for each macro call on a wiki page
title         = title-text   # The headline shown above the chart. Default: blank.
chart_type    = bar|line|pie # Optional; default: bar
query         = sql-query    # Mandatory
width         = pixel-width  # Optional; default: 600 
height        = pixel-height # Optional: default: 400
top_margin    = pixel-height # Optional; default: 50
bottom_margin = pixel-height # Optional; default: 30
left_margin   = pixel-height # Optional; default: 5
right_margin  = pixel-height # Optional; default: 5
}}}

The default margin sizes are a compromise that will fit many bar and pie charts, but expect to fiddle a bit with the margins if your query returns e.g. many long-named categories for a pie chart.

All defaults can be modified through the admin panel "yachart".

The background of this plugin is also discussed in [gdiscussion:trac-users:uNnJinrqW6Y].
 
== !Bugs/Feature Requests

Existing bugs and feature requests for TracYetAnotherChartMacro are 
[report:9?COMPONENT=TracYetAnotherChartMacro here].

If you have any issues, create a 
[/newticket?component=TracYetAnotherChartMacro new ticket].

[[TicketQuery(component=TracYetAnotherChartMacro&group=type,format=progress)]]

== Download

Download the zipped source from [export:tracyetanotherchartmacro here].

== Source

You can check out TracYetAnotherChartMacro from [/svn/tracyetanotherchartmacro here] using Subversion, or [source:tracyetanotherchartmacro browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Recent Changes

[[ChangeLog(tracyetanotherchartmacro, 3)]]

== !Author/Contributors

**Author:** [wiki:thenor] [[BR]]
**Maintainer:** [[Maintainer]] [[BR]]
**Contributors:**