Module overview
The operation and testing of custom modules is the responsibility of the module creator. Perforce Software, Inc. is not responsible for the operation of your custom modules, nor does Perforce Software, Inc. make any representations or warranties regarding the interoperability of your custom modules with Helix Swarm.
You must test your custom modules on a test system before transferring them to your production system. This avoids any negative impact on the operation of your production system. If you have more than one custom module, the modules should all be tested at the same time on the same test system as this ensures that the modules operate correctly with each other and with Helix Swarm.
A Swarm custom module is created in a folder in the modules folder of your Swarm installation. The folder name must match the custom module name and must contain at least a Module.php file and a module.config.php file. A custom module will not work in Swarm until you enable it. Enable your custom modules in Swarm by adding them to the custom.modules.config.php file in the config directory (a peer of the modules directory).
This chapter provides basic information about how custom modules integrate with Swarm and assumes a basic knowledge of the Zend framework. For more information about the Zend framework, see Zend 3 Quick Start documentation.
This section includes:
- Upgrade existing custom modules to the Zend 3 framework
- Influence activity events, emails, etc.
- Templates
- View helpers
- Further reading , includes links to example custom modules and the official Zend documentation
Upgrade existing custom modules to the Zend 3 framework
Swarm 2019.1 uses the Zend 3 framework, previous Swarm versions used the Zend 2 framework. The move to Zend 3 is part of our commitment to move away from using versions of platforms that have reached End-of-Life (EOL).
If you have any custom Swarm modules that were created for Swarm 2018.3 or earlier you must update them so that they will work in Swarm 2019.1 and later. For instructions on updating modules to the Zend 3 framework, see Upgrade custom modules to work with Zend 3.
Influence activity events, emails, etc.
When something happens in Helix Server (change submitted, files shelved, job added/edited), or state changes within Swarm (comment added, review state changed, etc.), the event is pushed onto the Swarm task queue. A background worker process 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 custom module can pay attention to specific types of events. While your custom 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 custom 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 events module processes it. The events module is a good example of subscribing to these events:
swarm_install/module/Events/config/module.config.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).
Event priority is from the highest positive number to the lowest negative number with 0 in the middle. For a full list of tasks and their event priorities, see Task details.
Task types
For details of each of the following tasks, see Task details.
- task.commit
- task.shelve
- task.review
- task.change
- task.mail
- task.cleanup.attachment
- task.cleanup.archive
- task.shelvedel
- task.changesave
- task.changesaved
- task.comment
- task.comment.batch
- task.commentSendDelay
- task.group
- task.groupdel
- task.job
- task.user
- task.userdel
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.
For more information about views, see the Zend/View Quick Start.
Swarm supports Zend version 3.2.0, features and functions in the Zend documentation that were introduced in later versions of Zend will not work with Swarm.
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/View/Helper/Foo.php
. Use the following Swarm view helper for inspiration: swarm_install/module/Activity/src/View/Helper/Activity.php
Then register your view helper with the view manager via your ModuleConfig
: swarm_root/module/Activity/config/module.config.php
Further reading
For detailed information about the Zend framework and examples see the following:
- The Zend 3 Quick Start documentation and Zend 3 framework documentation portal, it is useful to have a basic knowledge of the Zend framework before you create your own modules. .
- Example linkify module, a simple custom module that replaces a specific piece of text with a link for changelists, jobs, code review descriptions, comments, and activity entries.
- Example email module, a simple custom module that makes Swarm use a custom email template when it sends out when a comment notification is sent out.
- Swarm Jira module, a simple module implementation within Swarm: swarm_install/module/Jira
Swarm supports Zend version 3.2.0, features and functions in the Zend documentation that were introduced in later versions of Zend will not work with Swarm.
Your search for returned result(s).