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_install/module/Activity/config/module.config.php