
= Trac integration with Google Visualization API =

This plugin has been developped in order to expose the data managed by [http://trac.edgewall.org/ Trac] to widgets implemented using [http://code.google.com/apis/visualization Google Visualization API]. The following data is provided so far in the form of [http://code.google.com/apis/visualization data tables]:

  - Project components.
  - Project milestones.
  - Ticket priorities.
  - Ticket resolution values.
  - Ticket severity values.
  - Ticket status values.
  - Ticket types.
  - Project versions.

On the other hand, it will also allow [http://trac.edgewall.org/ Trac] users to use WikiFormatting in order to insert different widgets built with different [http://www.google.com/more Google APIs]. Until now this includes:

  - [http://www.google.com/ig iGoogle] [http://code.google.com\apis\gadgets gadgets]. In this case, the different [http://code.google.com/apis/visualization/documentation/gadgetgallery.html Visualization Gadgets] can be helpful to vary the way data managed by [http://trac.edgewall.org/ Trac] itself gets renderred in wiki pages, or maybe in third-party sites. Besides, some other [http://code.google.com\apis\gadgets gadgets] containing multiple informations, or even mini-applications, may be pasted in wiki pages. This may yields in ease of use, code reuse and, finally, lovely and useful [http://trac.edgewall.org/ Trac] sites. Since [http://www.google.com/ig iGoogle] [http://code.google.com\apis\gadgets gadgets] are displayed inside '''iframes''', security risks '''should''' be minimal ... however, consult [http://code.google.com/apis/gadgets/docs/spec.html gadgets specification] for more details.

== !ToDo ==

Outstanding tasks are :

[[TicketQuery(component=plugin_trac_gviz&priority=major, format=list, rows=id|summary)]]

== Dependencies ==

This plugin depends on the following components to be installed:

  - [http://peak.telecommunity.com/DevCenter/setuptools  setuptools]

  - [http://genshi.edgewall.org/ Genshi]
  
  - The [http://code.google.com/apis/visualization/documentation/dev/gviz_api_lib.html Data Source Python Library]
    must be installed so that the outputs be consistent with
    [http://code.google.com/apis/visualization/ Google Visualization API] [http://code.google.com/apis/visualization/documentation/dev/implementing_data_source.html data source protocol specification], and widgets can actually render the data managed by [http://trac.edgewall.org/ Trac] environments.

== Installation ==

This plugin has been tested with 
[http://trac.edgewall.org/ Trac] [http://trac-hacks.org/wiki/0.11 0.11.2]. You can see it in action [http://opensvn.csie.org/traccgi/swlcu here]. 

The first installation step is to [wiki:TracPlugins install this plugin] 
either for a particular environment or otherwise make it available to
all the environments:

{{{
$ easy_install /path/to/unpacked/TracGViz-x.y.z.zip
}}}

,, where ''x.y.z'' is the version of the plugin,,

... or alternately ...

{{{
$ easy_install TracGViz
}}}

In case of having internet connection and access to [http://pypi.python.org/pypi PyPI] or a simlar repository, both these methods '''should''' automatically retrieve the [#Dependencies external dependencies] from there.

== Configuration ==

In order to enable TracGViz plugin, the only thing to do is to add the
following lines to [wiki:TracIni trac.ini].

{{{
[components]
tracgviz.* = enabled
}}}

== What about coders ==



=== Design considerations ===

Hereinafter you will find some rules considered to develop this plugin. They are based in [http://code.google.com/apis/visualization/documentation/implementing_data_source.htm#overview a few basic rules] suggested by [http://www.google.com Google] engineers.

  - Trac accepts `HTTP GET` requests, however the site itself should be available to your clients.
  - Since the underlying protocol supports versioning, the solution provides [xxx extension points] to ease the task of adding protocol handlers for specific versions. Once they are implemented, your '''should''' support requests using previous versions as well as the current version since a built-in mechanism selects the handler matching the protocol version specified in the request. We'd really like to support new versions as soon as they are released to avoid breaking any clients that upgrade to the newest version quickly. However, time is a '''very''' scarce resource these days. There are two possible ways to overcome this situations:
    - '''Volunteer''' a little, [mailto://flioops.project@gmail.com?subject=TracGVizPlugin%20Patch submit patches], it will be great if many others contribute as well ... don't hesitate [mailto://flioops.project@gmail.com?subject=TracGVizPlugin%20add_member be part of the team].
    - Donate to this project (link available hopefully soon), so as to be able to leave everything else behind and fulfill your particular request. '''Time''' is more than '''gold'''.
  - We try to do everything so as to not fail if unknown properties are sent as part of the request. However, if you discover any bug, '''please''' [query:status=new|assigned|reopened|closed&component=plugin_trac_gviz find out related tickets]. If none is found then [/newticket?component=plugin_trac_gviz create a new ticket]. 
  - Conversely, built-in protocol handlers parse only the properties that they expect. If new versions introduce new properties, then the system uses the handler for the latest available version, and tries to send a response back to the client. [code.google.com/apis/visualization/documentation/querylanguage.html Google Visualization API query language] [ticket:xxx is not supported yet], but hopefully soon.
  - Some data sources '''may''' accept custom parameters for custom visualizations. However, they '''always''' return responses in the standard format.
  - Since third-party sites might be willing to use the data managed by your [http://trac.edgewall.org/ Trac] instance, it is very important to [ticket:xxx document the data source requirements] carefully. Due to the infinite possibilities offered by the plugin and [http://trac.edgewall.org/ Trac] architectures, and also since plugin developpers might want to implement their own data sources, the only feasible way to manage all this complexity is to automate documentation tasks. This feature is not ready, but will include (... in a near future ...) the following: 
    - Any custom parameters that you accept,
    - Whether or not [code.google.com/apis/visualization/documentation/querylanguage.html Google Visualization API query language] is supported, and ...
    - What kind of data is returned, and the structure of that data (what the rows and columns represent, and any labeling).
  - Integration with the [TracPermissions permissions system] has not being finished ... [ticket:xxx yet]. Therefore no standard security precautions have been taken, and the site may accept requests from unknown clients. Take this into consideration if you store any sensitive data.
  - All request and response strings '''should''' be UTF-8 encoded. Else, [/newticket?component=plugin_trac_gvi let us know].

== Bug / feature requests ==

Existing bugs and feature requests for [wiki:En/Devel/TracGViz TracGViz] are
[query:status=new|assigned|reopened&component=plugin_trac_gviz here].
If you have any issues, create a [/newticket?component=plugin_trac_gvi new ticket].


