= Growl notification dispatcher for Trac events =

[[PageOutline]]

== Description ==

This plugin dispatches change events that occur in a Trac project to 
Growl-enabled clients.

[http://growl.info/about.php Growl] is a notification system for Mac OS X: 
it allows applications that support Growl to send you notifications.

This plugin uses remote notifications, using the local network.[[br]]
The server may run on any OS, such as Linux, OS X, Windows or virtually any 
other OS that supports Trac.

The plugin does not rely on any 3^rd^ party libraries: no Growl SDK or library
is required on the Trac server.

Currently supported event sources:
 * Ticket creation, deletion, and update
 * Wiki page creation, deletion, and edition
 * Attachment creation and deletion
 * [http://bitten.edgewall.org Bitten] build startup, abortion and completion

=== Examples ===

[[Image(growl-ticket.png)]]

== Installation ==

Trac requirement:
 * Please read the version requirement defined in
  [browser:growlplugin/0.11/setup.py setup.py] file, search for ''install_requires''
 
=== Get the plugin source code ===

==== Download ====
Download the zipped source from [download:growlplugin here].
==== Source ====
You can check out GrowlPlugin from [http://trac-hacks.org/svn/growlplugin here] 
using Subversion, or [source:growlplugin browse the source] with Trac.

=== Build the plugin ===

As with any other plugin:
{{{
python setup.py bdist_egg
}}}

=== Installation of the plugin ===

Copy the generated egg file (from the `dist/` directory) to your project
plugin directory, or in the global plugin directory if you want to use it for
several Trac projects

=== Enabling the plugin ===

From the WebAdmin plugin interface or from your `trac.ini` file, enable the 
GrowlPlugin.

In `trac.ini`, edit the ''components'' section to add the revtree entry as 
follows:
{{{
[components]
growl.notifier.* = enabled
}}}

=== Configuration ===

The growl plugin can be configured with the help of the following settings.
The values defined in the following example represent the default values.
{{{
[growl]
sources = wiki, ticket, attachment, bitten
hosts =
userprefs = false
}}}
 * `sources` is a comma-separated list of source events.
   * `wiki` for wiki events,
   * `ticket` for ticket events,
   * `attachment` for attachment events
   * `bitten` for [http://bitten.edgewall.org bitten] build events, only 
available if bitten plugin is installed and enabled
 * `hosts` is a comma-separated list of network hosts to send notification to
   * if `hosts` is not defined, the notifications are broadcasted onto the LAN,
     which could be a security risks in some environments. You'll be warned
 * `userprefs` is a boolean option to allow per-user notification settings.
When enabled, any user who's been granted the `GROWL_MODIFY` permission may
select which notifications he wishes to receive, and the destination host
which the notifications should be sent to.

=== Permissions ===

The plugin defines two new permissions:
 * `GROWL_MODIFY` permission allows a user to change the notification settings
   through the Growl plugin perference panel, and choose the destination host 
   for the notifications
 * `GROWL_ADMIN` gives the same priviledges as `GROWL_MODIFY`, and allows the
   administrator to broadcast notfications to a sub network. To broadcast 
   notifications, the administrator should use the special '<broadcast>` host.

=== Warnings ===

==== Notification overload ====
Be warned that there is no restriction on the number of plugin users, which
might end up overloading a Trac installation if too many hosts are set to 
receive various Growl notifications. This plugin is mainly dedicated to small
team of users. Please also consider the use of the broadcast feature to 
reduce the number of notifications sent on every Trac event.

==== Security considerations ====
Your Trac-managed information may be at risk if you enable user preferences
(see `userprefs` setting) and some random user chooses a host that is located 
outside your LAN. Only give `GROWL_MODIFY` permission to trusted user. 

Moreover, an untrusted user might set up his preferences to notify a foreign,
remote host. Please ensure that Growl notifications are not routed
outside your own network (''UDP:9887'') .

You've been warned.

== Preferences ==

When a user is granted the `GROWL_MODIFY` permission, the Growl plugin 
preference panel appears under the user preferences view:

[[Image(growl-userpref-panel.png)]]

A user which is granted the `GROWL_ADMIN` permission may select the `<broadcast>` 
special host address to broadcast notifications to all the hosts
on the subnet.

== Client configuration ==

=== Growl installation ===

Follow growl 
[http://growl.info/documentation/growl-package-install.php installation instructions]

=== Growl configuration ===

Growl should be configured to accept incoming notifications and remote 
application registration.
  1. Open Mac OS X system preferences
  1. Select the Growl icon in the "''Other''" section
  1. Select the "''Network''" pane
  1. Enable the following check boxes
     * ''Listen for incoming notifications''
     * ''Allow remote application registration''
  1. Leave the "''Server password''" field empty

[[Image(growl-configuration.png)]]

==== Notes ====

Growl server passwords are not currently supported.

== Bugs/Feature Requests == 

This plugin is highly experimental (in early development stage)

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

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=GrowlPlugin&owner=eblot new ticket].


== Recent Changes ==

[[ChangeLog(growlplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:eblot] [[BR]]
'''Contributors:'''