A Quick Tour of the Swarm Sample Projects

This project contains a number of simple examples of how the behavior of Swarm can be modified to suit your needs. In broadstrokes there are two paths to modifying Swarm; you can add Javascript and CSS to the 'public/custom' directory in your Swarm deployment or you can write PHP based Zend modules and place them in the 'modules' directory of your Swarm deployment. Javascript/CSS baed modifications are by far the easiest and most resilient to change bewtween releases, but if you want to create new pages or modify the activity feed you will need to jump into PHP.

Whenver we possible we advise avoiding changes to the core PHP code shipped by Perforce; upgrading will potentially be much more challenging if you change the core code.

Notes on PHP Extensions

It is important to note that with Zend Framework 2 the namespace that you put in your Module.php file for your module needs to match the directory it is put in inside of the 'modules' directory. For example the 'HelloWorld' project has a namespace of 'HelloWorld' and all of the required code lives in a directory called 'HelloWorld'. This is one of the most common reasons for a project to fail to load, especially when copying and pasting example code, so be aware of your naming. When developing you will need to restart Apache to have it pick up your changes.

Notes on js/CSS Extensions

Any Javascript or CSS can be loaded into Swarm by dropping the files in the 'public/custom' directory of your Swarm installation. By default the 'custom' directory does not exist, although the test environment we provide will automatically create it for you. There's no need to restart Apache after changing the Jacascript or CSS files; they are automatically loaded when the browser is refreshed.

The Projects

HelloWorld

This PHP module shows how to modify events before they are published to the Swarm activity feed. In this case we replace most of the activity text with 'HelloWorld'. To install, copy the 'HelloWorld' directory into the 'modules' directory in your Swarm installation and restart Apache.

GoodbyeCruelWorld

This PHP module shows how to block events that you do not want in the activity. You may for example want to prevent all activity from automated processes to be blocked. To install, copy the 'GoodbyeCruelWorld' directory into the 'modules' directory in your Swarm installation and restart Apache.

DingoWorld

This module shows how to generate new activity based on incoming activity. First we generate an event and stick it in the event queue. When it comes through the next time we flesh it out. This module also shows you can attach to multiple events in one module. To install, copy the 'DingoWorld' directory into the 'modules' directory in your Swarm installation and restart Apache.

CloneWorld

This module demonstrates firiing off a new event based on the content of the event that is passed in. It also shows how we can run our own Perforce commands and work with the results. To install, copy the 'CloneWorld' directory into the 'modules' directory in your Swarm installation and restart Apache

Hello

This PHP module adds a new page to Swarm at http://my.swarm/hello. This is a helpful example of how you can add your own page to Swarm. To install, copy the 'Hello' directory into the 'modules' directory in your Swarm installation and restart Apache.

ChuckNorris

This PHP module triggers on new submissions and inspects the file contents to automatically add comments to the file based on regex matches. It's an excellent example of how to run Perforce comand and manipulate Swarm based on the results. To install it, drop the 'ChuckNorris' directory into the 'modules' directory in your Swarm installation and restart Apache.

javascript_tweaks

This directory contains snippets of Javascript that can be used to change the behavior or appearance of Swarm. Dropping any of these into your 'public/custom' directory will cause them to be used immediately.

css_tweaks

This directory contains snippets of CSS that can be used to change the behavior or appearance of Swarm. Dropping any of these into your 'public/custom' directory will cause them to be used immediately.

dev_env

This directory contains a Vagrantfile and some Puppet files to generate a test environment for your Swarm development. The README in that directory details how to get started with working on Swarm very quickly.