Modules
A Swarm module is a folder that exists within the
modules folder within your Swarm installation, where
the folder name matches the module's name, and that folder must contain (at
a minimum) a Module.php file. The file
Module.php describes the dependencies, namespace,
events subscriptions, and otherwise how the module integrates with Swarm.
This chapter provides only cursory coverage of how modules integrate with
Swarm. Refer to the included Jira module for a good
example of a simple module implementation within Swarm:
swarm_install/module/Jira
Influence activity events, emails, etc.
When something occurs in Perforce (change submitted, files shelved, job added/edited), or state changes within Swarm (comment added, review state changed, etc.), the event is pushed onto a task queue. A background worker process subsequently pulls events off of the queue and publishes an event alerting modules about activity they may be interested in processing. This architecture allows the Swarm user interface to be fairly quick while accommodating tasks that might require notable processing time, or need to wait for related information to become available.
Subscribers to the worker event flesh the item out (fetch the change/job details, for example) and indicate if it should result in an activity entry, email notification, etc. By subscribing to various event topics, your module can pay attention to specific types of events. While your module is processing an event, it can modify the text of activity events, change the contents of emails, drop things entirely from activity, etc.
When your module subscribes to an event, set the priority to influence how early or late in the process it runs. You will likely want your module to run after most other modules have done their work to flesh out the event, but before Swarm's activity module processes it. The activity module sets a good example of subscribing to these events:
swarm_install/module/Activity/Module.php
Note that its priority is set to -100. Select a value before that for your own module (for example, 0 would be neutral and -90 would indicate that you are interested in being last).
The activity module listens to all events. However, be more
selective. For example, if you are only interested in changes,
subscribe to task.change instead of
*. Current task types are:
-
task.change -
task.shelve -
task.review -
task.comment -
task.job
Templates
Override existing view templates using your custom module. Have a look at an example module that demonstrates how to customize the email templates Swarm uses for comment notifications.
Tip
For more information about views, see the Zend/View Quick Start.
View helpers
Set options on existing helpers
It is possible to influence the behavior of existing view helpers by
setting options on them; for an example see:
swarm_install/module/Application/Module.php
Register new helpers
It is also possible to register new view helpers by placing them
within your module's hierarchy, for example,
MyModule/src/MyModule/View/Helper/Foo.php. Use the
following Swarm view helper for inspiration:
swarm_install/module/Activity/src/Activity/View/Helper/Activity.php
Then register your view helper with the view manager via your
ModuleConfig:
swarm_root/module/Activity/config/module.config.php