Helix Swarm Guide (2019.2)

Example linkify module

Tip

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.

Note

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.

The following example module demonstrates how to turn text that appears in changelist, job, or code review descriptions, comments, and activity entries into links.

Basic steps needed to create the Email Example module are:

File locations

For reference, the Rickroll module uses the following filenames and locations:

config/
      custom.modules.config.php
module/
      Rickroll/
               config/
                      module.config.php
               Module.php

Create the Module.php file

Module.php will:

  • Declare the module namespace, this must match the directory name of the module.
  • Provide the Linkify application.
  • Provide the onBootstrap() function.
  • Add a callback to the Linkify module that declares what text is to be searched for (rickroll) and, when found, how to compose the link for that text.
  • Provide the getConfig() function.

Create the Module.php file:

  1. Create a directory called Rickroll in the module directory.
  2. Create the file Module.php in module/Rickroll.

  3. Edit Module.php to contain:
  4. <?php
    /**
     * Perforce Swarm
     *
     * @copyright   2019 Perforce Software. All rights reserved.
     * @license     Please see LICENSE.txt in top-level folder of this distribution.
     * @version     <release>/<patch>
    */
    
    namespace Rickroll;
    
    use Application\Filter\Linkify;
    
    class Module
    {
        public function onBootstrap()
        {
            Linkify::addCallback(
                // Linkify requires 3 parameters: "$linkify", "$value" and "$escaper" 
                function ($linkify, $value, $escaper) {
                    if (strcasecmp($value, 'rickroll')) {
                        // not a hit; tell caller we did not handle this one
                        return false;
                    }
    
                    return '<a target="_new" href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">'
                               . $escaper->escapeHtml($value) . "</a>";
                },
                'rickroll',
                strlen('rickroll')
            );
        }
    
        public function getConfig()
        {
            return include __DIR__ . '/config/module.config.php';
        }
    }
  5. Now Create the module.config.php file.

Create the module.config.php file

  • The module.config.php file is required but for the linkify module only has an empty return.
  • Create the module.config.php file:

    1. Create a file called module.config.php in Rickroll/config.
    2. Edit module.config.php to contain:
    3. <?php
      /**
      * Perforce Swarm
      *
      * @copyright 2019 Perforce Software. All rights reserved.
      * @license Please see LICENSE.txt in top-level folder of this distribution.
      * @version <release>/<patch>
      */
      { return array(); }
    4. Now Enable the Rickroll module for Swarm in custom.modules.config.php.

    Enable the Rickroll module for Swarm in custom.modules.config.php

    Swarm uses the custom.modules.config.php file to auto-load classes and to check which custom modules it should run. This gives you control over which modules Swarm loads and prevents modules from being loaded by mistake.

    Create the custom.modules.config.php file:

    1. Create the config directory at the same level as the module directory if it does not exist.
    2. Create the custom.modules.config.php file in the config directory if it does not exist.
    3. Edit the custom.modules.config.php file so that it contains the auto-loader and the Rickroll module details:
    4. Tip

      If you already have one or more custom modules enabled for Swarm, the auto-loader and the existing module details will already be in the file.

      Just add Rickroll to the namespaces and return arrays of the custom.modules.config.php file.

      <?php
      \Zend\Loader\AutoloaderFactory::factory(
          array(
              'Zend\Loader\StandardAutoloader' => array(
                  'namespaces' => array(
                      'Rickroll'      => BASE_PATH . '/module/Rickroll',
                  )
              )
          )
      );
      return [
          'Rickroll'
      ];
      

    5. The Rickroll module is now enabled for Swarm. Swarm will now turn text that appears in changelist, job, or code review descriptions, comments, and activity entries into links.
    6. The Rickroll module is now enabled for Swarm. Swarm will now replace the text "rickroll " with a link to "https://www.youtube.com/watch?v=dQw4w9WgXcQ".
    7. Check that the module works correctly before moving it to your production server.