メニューヘルパー

menu_helpers構成ブロックを使用して、Swarmのメニュー項目の表示を制御し、URLとSwarmモジュール用の新しいメニュー項目を作成します。

メニュー項目をメニューに追加する

SWARM_ROOT/data/config.phpファイルのmenu_helpers構成ブロックで、Swarmのメニュー項目を追加します。以下に例を示します。

<?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,                  // ['true'|'false'] 'true' makes the menu item visible. 'true' is the default 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, appended to h2.menu- in Swarm CSS
            '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
        ),
    ),

構成可能変数

• id: Swarmのメニュー項目で使用される一意のIDです。任意の値を指定することができます。 idが配列に含まれていない場合、Swarmは親配列の名前を使用します。
• 有効
  • 値としてtrueを設定すると、rolesの値によって適用される制限に従ってメニュー項目が表示されます。 enabledが配列に含まれていない場合は、trueがデフォルト値になります。
  • 値としてfalseを設定すると、メニュー項目が非表示になります。
• target: メニュー項目をクリックしたときに使用されるURLまたはSwarmモジュールのルート。 targetが配列に含まれていない場合、Swarmは、ルートに対してidの値を使用します。 idが配列に含まれていない場合、Swarmは、ルートに対して親配列の名前を使用します。
• cssClass: メニュー項目のCSSクラスを指定します。このクラスを使用して、メニュー項目にカスタムアイコンを追加します。詳しくは、カスタムアイコンをメニュー項目に追加するを参照してください。 cssClassの値はh2.menu-に追加され、メニュー項目のCSSクラスが作成されます。 上記の例では、h2.menu-custom_menuのCSSクラスが作成されます。 デフォルトでは、cssClassを指定しなかった場合、Swarmによってシェブロンアイコン(>)がメニュー項目に追加されます。
• title: メニューに表示されるメニュー項目の名前を指定します。 titleが配列に含まれていない場合、Swarmは、メニュー項目に対してidの値を使用します。 idが配列に含まれていない場合、Swarmは、メニュー項目に対して親配列の名前を使用します。
• class: メニュー項目を、メインメニューとプロジェクトメニューのどちらに表示するかを指定します。
  classの値として
  • ''を指定した場合、またはclassが配列に含まれていない場合は、メインメニューにメニュー項目が追加されます。
  classの値として「
  • \Projects\Menu\Helper\ProjectContextMenuHelper」を指定すると、すべてのプロジェクトのプロジェクトメニューにメニュー項目が追加されます。
ヒント

ProjectAwareMenuHelperモジュールを拡張すると、メニュー項目の追加先を特定のプロジェクトだけに制限することができます。詳しくは、特定のプロジェクトのプロジェクトメニューにメニュー項目を追加するを参照してください。

• priority: メニューに表示されるメニュー項目の位置を指定します。指定する数値が小さいほど、メニュー構造の上位に表示されます。 priorityが配列に含まれていない場合、Swarmメニューの最下部に対象のメニュー項目が表示されます。 既存のメニュー項目と同じpriority値を使用すると、同じpriority値を持つメニュー項目がアルファベット順に表示されます(この方法はお勧めしません)。
ヒント

ブラウザのアドレスバーに「<yourSwarmURL>/api/v10/menus」を入力すると、Swarmのメニュー項目に対するpriority値の一覧が表示されます。

• roles: ログインしているユーザの権限に従い、メニュー項目の表示を制限します。以下の値を指定することができます。
  • null: ユーザの権限に関係なく、すべてのユーザに対してメニュー項目が表示されます。 rolesに値を設定しなかった場合や、rolesが配列に含まれていない場合は、nullがデフォルト値として使用されます。
  • authenticated: すべての認証済みユーザに対してメニュー項目が表示されます。
  • admin: Perforceでadmin 以上の権限を持っているすべてのユーザに対して、メニュー項目が表示されます。
  • super: Perforceで super 権限を持っているすべてのユーザに対して、メニュー項目が表示されます。

カスタムアイコンをメニュー項目に追加する

メニュー項目に対して指定されたcssClassの値は、Swarm CSSのh2.menu-に付加されます。

これにより、カスタムのCSSをSwarmに追加して、メニュー項目のデフォルトアイコンを変更することができます。 例えば、CSSを以下のように指定すると、custom-menuのcssClassを使用して、double-speech-bubbles.svgアイコンがメニュー項目に追加されます。

.swarm-menu-item.menu-custom-menu .svgIcon{
    display:none;
}
.swarm-menu-item.menu-googleMain a::before{
    content: '';
    background-image: url('/swarm/img/icons/line/double-speech-bubbles.svg');
    background-size: 16px;
    background-repeat: no-repeat;
    padding-left: 18px;
}

adminレベル以上の権限を持つユーザだけに[グループ]メニュー項目を表示する

[グループ]メニュー項目の表示設定をより詳細に管理する必要がある場合は、menu_helpers構成ブロック内にgroupsブロックを作成し、必要に応じてrolesを設定します。 この例では、rolesの値が'admin'に設定されているため、admin 以上のアクセス権限を持っているユーザに対してのみ、[グループ]メニュー項目が表示されることになります。

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

カスタムモジュール名だけを使用してメニュー項目を作成する

Swarmのカスタムモジュールが作成されている場合は、そのカスタムモジュールのルートを使用するメニュー項目を作成することができます。menu_helpers構成ブロック内で、メニュー項目用の構成可能変数を追加する必要はありません。

例えば、'codeAnalytics'のルートを持つカスタムモジュールが存在する場合は、構成ブロックを以下のように設定するだけで済みます。

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

codeAnalysisメニューに対するその他の構成可能変数の値は、すべてデフォルト値に設定されます。これは、codeAnalysis配列が空になっているためです。

• id: 使用する親配列の名前(codeAnalysis)。
• enabled = true: メニュー項目が有効になります。
• target: 使用する親配列の名前(codeAnalysis)。この名前は、カスタムモジュール名と一致している必要があります。
• cssClass: クラスは設定されません。Swarmは、メニュー項目に対して、デフォルトのシェブロンアイコン(>)を使用します。
• class: クラスは設定されません。メニュー項目は、メインメニュー内に表示されます。
• priority: 優先順位は設定されません。メニュー項目は、Swarmメニューの最下部に表示されます。
• roles: null: ユーザの権限に関係なく、すべてのユーザに対してメニュー項目が表示されます。

特定のプロジェクトのプロジェクトメニューにメニュー項目を追加する

特定のプロジェクトのプロジェクトメニューにメニュー項目を追加するには、ProjectAwareMenuHelperヘルパーを展開し、このヘルパーを使用するようにclassメニュー項目を設定します。

以下の例では、[Jam]というプロジェクトメニューで[Jenkins Build]というメニュー項目だけを表示しています。

ProjectAwareMenuHelperを展開する

ここでは、ProjectAwareMenuHelperヘルパーを展開し、[Jam]というプロジェクトメニューで[Jenkins Build]というメニュー項目だけを表示する方法について説明します。 このヘルパーの名前は自由に設定でき、任意の場所に保存できますが、わかりやすい名前を付けて適切な場所に保存する必要があります(この例では、/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;
  }
}

メニュー項目の定義

以下の構成ブロックで、[Jam]プロジェクトメニューに追加する[Jenkins Build]メニュー項目を定義します。 ここで重要なことは、classを\Projects\Menu\Helper\JamOnlyMenuItemに設定することです。これにより、Jamプロジェクトに[Jenkins Build]メニュー項目だけが表示されるようになります。

<?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'],
        ),
    ),

Swarm構成キャッシュを再ロードしてメニュー項目を有効にする

Swarmの構成に対する変更内容は、構成キャッシュを再ロードするまで反映されません。構成キャッシュを再ロードすると、新しい構成情報がSwarmで強制的に使用されます。 Swarm構成キャッシュを再ロードするには、admin ユーザまたはsuper ユーザでなくてはなりません。 [ユーザID]ドロップダウンメニューに移動して[システム情報]を選択し、[キャッシュ情報]タブをクリックしてから[構成の再ロード]ボタンをクリックします。