Menu helpers

The menu_helpers configuration block is used to control the visibility of Swarm menu items and to create new menu items for URLs and Swarm modules.

Add a menu item to a menu

Add Swarm menu items in the menu_helpers configuration block in the SWARM_ROOT/data/config.php file, as in the following example:

<?php
    // this block should be a peer of 'p4'
    'menu_helpers' => array( 
        'MyMenu01' => array( // A short recognizable name for the menu item
            'id'        => 'custom01',            // A unique id for the menu item. If not included in the array, parent array name is used.
            'enabled'   => true,                  // When set to true, the menu item is visible. Defaults to true if not included in the array.
            'target'    => '<https://MyWebite>',  // The URL or custom module route a menu click takes you to.
                                                  // If not included in array, id is used. If id not included, parent array name is used. 
            'cssClass'  => 'custom_menu',         // The custom CSS class name added to the menu item.
            'title'     => 'MyMenuItem',          // The text that will be shown on the button.
                                                  // If not included in array, id is used. If id not included, parent array name is used.
            'class'     => '',                    // If not included in array or empty, the menu item is added to the main menu.
                                                  // To add the menu item to the project menu for all of the projects, set to '\Projects\Menu\Helper\ProjectContextMenuHelper'
            'priority'  => 155,                   // The position the menu item is displayed at in the menu. 
                                                  // If not included in the array, the menu item is placed at the bottom of the menu.  
            'roles'     => null,                  // null|'authenticated'|'admin'|'super' 
                                                  // If not included in the array, null is the default
                                                  // Specifies the minimum level of Perforce user that can see the menu item. 
                                                  // 'authenticated' = any authorized user, null = unauthenticated users
        ),
    ),

Configurables

• id a unique id used by Swarm for the menu item, this can be anything. If id is not included in the array, Swarm uses the name of the parent array.
• enabled
  • true the menu item is visible subject to restrictions imposed by the roles value. This is the default value if enabled is not included in the array.
  • false the menu item is not in use
• target the URL or Swarm module route used when the menu item is clicked. If target is not included in the array, Swarm uses the id for the route. If id is not included in the array, Swarm uses the parent array name for the route.
• cssClass specifies the CSS class for the menu item, used to replace the default icon with a custom icon for the menu item, see Add a custom icon to a menu item.
• title specifies the menu item name displayed in the menu. If title is not included in the array, Swarm uses the id for the menu title. If id is not included in the array, Swarm uses the parent array name for the menu title.
• class specifies whether the menu item is displayed in the main menu or the project menu.
  • '' or not included in the array, adds the menu item to the main menu.
  • \Projects\Menu\Helper\ProjectContextMenuHelper adds the menu item to the project menu of all of your projects.
Tip

You can restrict the menu item to a specific project by extending the ProjectAwareMenuHelper module, see Add a menu item to the project menu of a specific project.

• priority specifies the menu item position in the menu, lower numbers are displayed higher up the menu structure. If priority is not included in the array, the menu item is placed at the bottom of the Swarm menu. If you use the same priority value as an existing menu item (not recommended), the menu items with the same priority are displayed in alphabetical order.
Tip

Enter <yourSwarmURL>/api/v11/menus in your browser address bar to return a list of the priority values for the Swarm menu items.

• roles restrict the display of the menu item based on the permissions of the logged in user:
  • null menu item visible to any user even if they are not authenticated. if roles is empty or not included in the array, null is used as the default.
  • authenticated menu item is visible to any authenticated user
  • admin menu item is visible to any user with Perforce admin permissions or higher
  • super menu item is visible to any user with Perforce super user permissions

Add a custom icon to a menu item

Add some custom CSS to Swarm to replace the default icon with a custom icon for the menu item. For example, the CSS below replaces the default icon with the double-speech-bubbles.svg icon for the custom01 menu item by modifying the svg.svgIcon.custom01MenuIcon and .menuItem-custom01 classes:

.swarmMenu .menuItem.menuItem-tests .svgIcon{
    display:none;
}.swarmMenu .menuItem.menuItem-tests a::before{
    content: '';
    background-image: url('/swarm/img/icons/line/double-speech-bubbles.svg');
    background-size: 16px;
    background-repeat: no-repeat;
    padding-left: 20px;
        padding-right: 4px;
        margin-left: 20px;
}

Save these lines in a file, perhaps menu_custom01.css in a folder called custom_menus, in the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately using your custom menus for subsequent page views. If you are using your own custom images, we recommend you store them in the same folder as your custom css.

Make Groups menu item visible to admin-user and above only

If you need fine grained control over the visibility of the Groups menu item, create a groups block in the menu_helpers configuration block and set the roles as required. In this example roles is set to 'admin' so that only users with admin-user access and higher will be able to see the Groups menu item:

<?php
    // this block should be a peer of 'p4'
    'menu_helpers' => array( 
        'groups' => array( 
            'roles'     => 'admin', 
        ),
    ),

Create a menu item using only the custom module name

If you have created a Swarm custom module you can create a menu item for it that uses the custom module route and you do not need to add any other configurables for it in the menu_helpers configuration block.

For example, if you have a custom module with a route of 'codeAnalytics', the configuration block only needs to be:

<?php
    // this block should be a peer of 'p4'
    'menu_helpers' => array(
        'codeAnalytics' // links the menu item to a module called 'codeAnalytics' 
    ); 

All of the other configurable settings for the codeAnalysis menu item will be set to their default values because the codeAnalysis array is empty:

• id: parent array name used (codeAnalysis)
• enabled = true, menu item is enabled
• target: parent array name used (codeAnalysis), this must match the custom module name
• cssClass: no class is set and Swarm uses the default chevron > icon for the menu item
• class: no class is set, the menu item is displayed in the main menu
• priority: no priority is set, the menu item is displayed at the bottom of the Swarm menu
• roles: null, visible to all users even if they are not authenticated

Add a menu item to the project menu of a specific project

To add a menu item in the project menu of a specific project, extend the ProjectAwareMenuHelper and set the menu item class to use the extended helper.

The example in this section only displays the Jenkins Build menu item in the Jam project menu.

Extend the ProjectAwareMenuHelper

Extend the ProjectAwareMenuHelper so that the Jenkins Build menu item is only displayed in the Jam project menu. This helper can be called anything and saved anywhere but it should have a descriptive name and be in a logical place, in this example it is /modules/Project/src/Menu/Helper/JamOnlyMenuItem.php:

<?php
  /**

  * Perforce Swarm
  * @copyright 2020 Perforce Software. All rights reserved.
  * @license Please see LICENSE.txt in top-level folder of this distribution.
  *@version <release>/<patch>
  */
 
namespace Projects\Menu\Helper;
 
  /**
  * Only show the menu item using this class for the specified Project.
  * In this example it is for the project with the id of Jam.
  * Class JamOnlyMenuItem
  * @package Projects\Menu\Helper
  */
class JamOnlyMenuItem extends ProjectAwareMenuHelper
{
    /**
    * Modifies an item's target if the context is for a project, the project supports the item and
    * the item already has a target. Otherwise, nullify the item
    * @return array|null
    */
  public function getMenu()
  {
    if ($this->project && $this->project->getId() === 'jam') {
      $item = parent::buildMenu();
      // Allow project characteristics to determine menu item availability
      return !empty($this->project) && $this->isDisabled() === false ? $item : null;
    }
    return null;
  }
}

Define your menu item

The following block defines the Jenkins Build menu item you are adding to the Jam project menu. The important part is that class is set to \Projects\Menu\Helper\JamOnlyMenuItem so that it is only displayed in the Jam project.

<?php
    // this block should be a peer of 'p4'
    'menu_helpers' => array( 
        'jenkins_jam' => array( // A short recognizable name for the menu item
            'id'        => 'jenkins_jam',
            'enabled'   => true,
            'target'    => 'http://my-jenkins.instance.jam.com',  
            'cssClass'  => 'custom_menu',
            'title'     => 'Jenkins Build', 
            'class'     => '\Projects\Menu\Helper\JamOnlyMenuItem',   
            'priority'  => 160, 
            'roles'     => ['authenticated'],
        ),
    ),

Delete Swarm config cache to enable the menu item

Your changes will not be used by Swarm until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.