[[PageOutline(2-5,Contents,pullout)]] = Graphs tables and other data using Google Visualization API = == Description == This plugin adds [http://code.google.com/apis/chart/ Google Visualization API] charts to Trac pages. The most basic usage is graphing an existing report: [[Image(effort.png, border=1)]] See more examples [wiki:VisualizationPlugin#Examples below]. See also: [http://pypi.python.org/pypi/TracGViz TracGViz plugin] == Configuration == 1. Install the plugin (after downloading and unzipping): {{{ #!sh cd visualizationplugin/0.12 sudo python setup.py bdist_egg sudo cp dist/TracVisualization*.egg /your/trac/location/plugins/ }}} See [http://trac.edgewall.org/wiki/TracPlugins TracPlugins] for more installation details and options. You'll likely need to restart Trac's web server after installation. 2. Enable the plugin: {{{ #!ini [components] viz.* = enabled }}} You can alternatively use the Trac Web Admin GUI to enable any or all rules. 3. Configure which pages to include graphs - example: {{{ #!ini [viz] reports = 21 }}} The above example will populate an area chart from the table of data found in report 21 and display the chart above that table - see screenshot above. The examples section [wiki:VisualizationPlugin#Examples below] shows additional ways to include graphs and charts on Trac pages. This plugin requires Javascript but does not require any other libs to be pre-installed. The Google Visualization libs are loaded dynamically using Google's standard JS loader. == Bugs/Feature Requests == Existing bugs and feature requests for VisualizationPlugin are [report:9?COMPONENT=VisualizationPlugin here]. If you have any issues, create a [http://trac-hacks.org/newticket?component=VisualizationPlugin&owner=robguttman new ticket]. == Download == Download the zipped source from [download:visualizationplugin here]. == Source == You can check out VisualizationPlugin from [http://trac-hacks.org/svn/visualizationplugin here] using Subversion, or [source:visualizationplugin browse the source] with Trac. == Examples == === Existing report === The most basic usage is adding a chart to an existing report - this can be achieved with almost no configuration. Simply list the reports in the {{{[viz]}}} section in {{{trac.ini}}}: {{{ #!ini [viz] reports = 21,23 }}} The plugin will automatically determine the data types for each column. However, the table needs to be structured suitably for graphing. In the screenshot at the top of this page, the table was built by grouping tickets into weeks as follows (sqlite SQL): {{{ #!sql SELECT date(tc.time/1000000, 'unixepoch', 'weekday 5') as "Week ending", SUM(CASE e.value WHEN '' THEN 0 ELSE e.value END) AS effort FROM ticket t JOIN ticket_change tc ON tc.ticket = t.id AND tc.field = 'status' AND tc.newvalue='closed' AND tc.time=(SELECT max(time) FROM ticket_change tc2 WHERE tc2.ticket = t.id AND tc2.field = 'status' AND tc2.newvalue='closed') LEFT OUTER JOIN ticket_custom e ON e.ticket = t.id and e.name = 'effort' WHERE resolution = 'fixed' AND t.type != 'epic' GROUP BY date(tc.time/1000000, 'unixepoch', 'weekday 5') ORDER BY date(tc.time/1000000, 'unixepoch', 'weekday 5') }}} The above is only for illustration purposes. Any SQL query can be used as long as it produces a graphable table. If you prefer a column chart instead of the default area chart, you can change the chart type as follows: {{{ #!ini [viz] reports = 21,23 type = ColumnChart }}} The type name must exactly match those supported by the Google Visualization API [http://code.google.com/apis/chart/interactive/docs/gallery.html here] (no spaces). You can also customize all of its options available for that chart type. For example, the {{{ColumnChart}}} type's options can be found [http://code.google.com/apis/chart/interactive/docs/gallery/columnchart.html#Configuration_Options here]. So if we wanted to add a title and change the color for the same table as shown in the screen at the top of this page, we can do this: {{{ #!ini [viz] reports = 21,23 type = ColumnChart options = width:600,height:400,colors:['green'],title='Whistle while we work' }}} [[Image(whistle.png)]] === Different graphs per report === If you use multiple graphs and charts, you may want to customize them differently for different reports. To do that, create a new section for the reports instead of including them in the main {{{[viz]}}} section's {{{reports}}} option: {{{ #!ini [viz] options = width:600,height:400 [viz.report/21] type = ColumnChart options = colors:['green'],title='Whistle while we work' [viz.report/23] type = AreaChart options = colors:['red'],title='Bugs baby!' }}} You customize a page's graph by creating a section that matches all or part of its url after a {{{viz.}}} prefix. So for example, the above customizes reports 21 and 23 differently. Report 21 will be a green column chart with the given title, and report 23 will be a red area chart with its given title. Both charts will inherit the {{{[viz]}}} section's width and height, however. '''Important''': whereas the {{{options}}} option ''adds'' to the base {{{[viz]}}} section's {{{options}}}, all other options (e.g., {{{type}}}) ''override'' the base {{{[viz]}}} section's options. === Burndown chart on milestone pages === In the examples above, the data for the charts came from a report table located on the same page. You can also create charts by [http://code.google.com/apis/chart/interactive/docs/queries.html querying remote data sources] that conform to the [http://code.google.com/apis/chart/interactive/docs/dev/implementing_data_source.html Google Visualization Data Source API]. One such example is the [wiki:SumStatsPlugin SumStats plugin] which provides a data source amenable to graphing as a daily burndown chart on any milestone page. For example: {{{ #!ini [viz.milestone] # Burndown type = ColumnChart options = width:400,height:300,title:'Burndown',colors:['blue','lightgray'],isStacked:true,backgroundColor:{strokeWidth:1,stroke:'#999'} source = https://trac.mycompany.com/sumstats/query selector = #stats fieldset }}} The above will add a daily, agile-style [http://en.wikipedia.org/wiki/Burn_down_chart burndown chart] to your milestone pages: [[Image(burndown.png)]] In the configuration above, the {{{source}}} specifies the data source (in this case the local sumstats plugin) and the {{{selector}}} specifies the DOM element where the graph should be inserted before (in this case just before the stats drilldown section). You can position graphs anywhere by specifying an appropriate jQuery selector. See the [wiki:SumStatsPlugin SumStats plugin] for details on how to configure it for alternative visualizations (e.g., by adding a {{{query}}} to specify the columns to return and their order). === Any graph on any page === As described above, you can add a graph or chart to any Trac page including wiki pages. The steps are: 1. Create a {{{[viz.]}}} section in {{{trac.ini}}} 1. Set its {{{source}}} option to the remote data source url 1. (Optional) Add a {{{query}}} option as appropriate for the data source 1. Set the {{{selector}}} to the DOM location before which the graph should be inserted 1. Configure the chart {{{type}}} and {{{options}}} as desired To embed iGoogle Gadgets in wiki pages using WikiFormatting, you may wish to try [http://pypi.python.org/pypi/TracGViz TracGViz plugin] (I have not yet tried this myself). == Recent Changes == [[ChangeLog(visualizationplugin, 3)]] == Author/Contributors == '''Author:''' [wiki:robguttman] [[BR]] '''Maintainer:''' [wiki:robguttman] [[BR]] '''Contributors:'''