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

= Creare 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 thanks to the full database access.
}}}

== Description

This macro allows you to create a bar/line/pie chart of an SQL query 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 ambiguous 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".

== !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:**