Difference between revisions of "Client Area Sidebars Cheatsheet"

Latest revision as of 19:57, 9 June 2022

The following guide is designed to provide some copy & paste ready code samples for common customisations performed to the dynamic sidebar menus. For more detailed documentation, please refer to Editing Client Area Menus

Important
This guide assumes you are already familiar with creating and using hook files in WHMCS. The following code examples will need to be placed within a hook file.

1 Finding a Sidebar Name
2 Changing the Text Label of a Sidebar Item
3 Changing where a Sidebar Item Points To
4 Re-arranging Sidebar Items
5 Adding an Additional Sidebar Menu Item
6 Custom Actions in the Service Details Sidebar Menu
7 Hiding/Removing a Sidebar Menu Item
8 Manipulate a Sidebar Menu Item by Name

Finding a Sidebar Name

Every sidebar menu item has a unique name that is used to reference it. You will need this name in order to manipulate it. To make it easier, we have made the name of each sidebar menu item available in the HTML source of the page, which means it can be retrieved using the Inspect Element option available in most modern browsers. An example of this is shown below.

Once you have the menu item name that you wish to manipulate, which in the example above is Account Details you can manipulate it in the following ways.

The client area's sidebar menu system is defined in a tree structure. Each menu item has one parent item and can have many child items. So when you're looking to manipulate a menu item within a sidebar panel, you will need to first retrieve the parent menu item, which in the case above is Account, followed by the Account Details menu item which is a child within that.

Changing the Text Label of a Sidebar Item

All sidebar menu items that are supplied by default use display names controlled by language file. Simply search in your active language file for the text you see in the menu item label, and you can adjust/change it there as required.

Alternatively, you can manipulate the display text via a hook as follows:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimarySidebar', 1, function(MenuItem $primarySidebar)
{
    $primarySidebar->getChild("My Account")
        ->getChild("Billing Information")
        ->setLabel("Custom Text Here");
});

Notice how in the above we first retrieve the Support menu item, followed by the Announcements menu item which is a child within that. The same logic should be applied to all dropdown menu items.

Changing where a Sidebar Item Points To

You can change where a menu item points to using the setUri method. For example if we are using an external system to control our announcements, we could do something like the following:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimarySidebar', 1, function(MenuItem $primarySidebar)
{
    $primarySidebar->getChild('My Account')
        ->getChild('Billing Information')
        ->setUri('https://www.example.com/billingInfo');
});

Re-arranging Sidebar Items

You can change the display order of menu items as follows:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimarySidebar', 1, function(MenuItem $primarySidebar)
{
    $primarySidebar->getChild('My Account')
        ->getChild('Billing Information')
        ->setOrder(25); // default menu items have orders 10, 20, 30, etc...
});

The following helpers are also available:

// Moves a menu item up one position
$primaryNavbar->getChild('My Account')->getChild('Billing Information')->moveUp();
// Moves a menu item down one position
$primaryNavbar->getChild('My Account')->getChild('Billing Information')->moveDown();
// Moves a menu item to the first position
$primaryNavbar->getChild('My Account')->getChild('Billing Information')->moveToFront();
// Moves a menu item to the last position
$primaryNavbar->getChild('My Account')->getChild('Billing Information')->moveToBack();

Adding an Additional Sidebar Menu Item

Before adding an item to a menu, check that the sidebar exists on that specific page. You can then add more menu items using code like the following example:

<?php
 
use WHMCS\View\Menu\Item as MenuItem;
add_hook('ClientAreaPrimarySidebar', 1, function (MenuItem $primarySidebar)
 
{
    if (!is_null($primarySidebar->getChild('My Account'))) {
        $primarySidebar->getChild('My Account')
    ->addChild('Mailing List Subscription Prefs')
        ->setLabel('Subscription Preferences')
        ->setUri('subscriptionprefs.php')
        ->setIcon('fa-user')
        ->setOrder(100);
    }
});

Custom Actions in the Service Details Sidebar Menu

In WHMCS 8.5 and later, you can use the CustomActions server module function to add items to the server details sidebar menu. The item will perform a set function and then redirect the user to a specified URL.

For more information about custom actions, see our Developer Documentation.
You can also use this to add custom actions to Client Area Home Page panels.

Hiding/Removing a Sidebar Menu Item

You can remove a menu item as follows:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimarySidebar', 1, function(MenuItem $primarySidebar)
{
    if(!is_null($primarySidebar->getChild('My Account')) && !is_null($primarySidebar->getChild('My Account')->getChild('Billing Information'))){
    $primarySidebar->getChild('My Account')->removeChild('Billing Information');
    }
});

Manipulate a Sidebar Menu Item by Name

You can also manipulate a menu item by name with the ClientAreaSidebars hook point. The following code would check to see which sidebar the element belongs to, and then allow you to act on it. In this example by removing it:

<?php
 
use WHMCS\View\Menu\Item as MenuItem;
 
add_hook('ClientAreaSidebars', 1, function() {
    $primarySidebar = Menu::primarySidebar();
    $secondarySidebar = Menu::secondarySidebar();
 
    $id = 'Client Contacts';
 
    if ($primarySidebar && !is_null($primarySidebar->getChild($id))) {
        $objectToWorkWith = $primarySidebar->removeChild($id);
    } elseif ($secondarySidebar && !is_null($secondarySidebar->getChild($id))) {
        $objectToWorkWith = $secondarySidebar->removeChild($id);
    }
 
    if ($objectToWorkWith) {
        $objectToWorkWith->removeChild($id);
    }
});

@@ Line 1: / Line 1: @@
 The following guide is designed to provide some copy & paste ready code samples for common customisations performed to the dynamic sidebar menus.  For more detailed documentation, please refer to [[Editing Client Area Menus]]
-This guide assumes you are already familiar with [[Hooks|creating and using Hook files in WHMCS]].
+<div class="docs-alert-success"><strong>Important</strong><br>This guide assumes you are already familiar with [https://developers.whmcs.com/hooks creating and using hook files in WHMCS].  The following code examples will need to be placed within a [https://developers.whmcs.com/hooks/getting-started/ hook file].</div>
 ==Finding a Sidebar Name==
@@ Line 7: / Line 7: @@
 Every sidebar menu item has a unique name that is used to reference it.  You will need this name in order to manipulate it.  To make it easier, we have made the name of each sidebar menu item available in the HTML source of the page, which means it can be retrieved using the Inspect Element option available in most modern browsers.  An example of this is shown below.
-[[File:Sidebar-inspect-element.png]]
+[[File:menus-find-name.png|700px]]
-Once you have the menu item name that you wish to manipulate, which in the example above is "Billing Information" you can manipulate it in the following ways.
+Once you have the menu item name that you wish to manipulate, which in the example above is '''Account Details''' you can manipulate it in the following ways.
-<div class="docs-alert-info">The client area's sidebar menu system is defined in a tree structure. Each menu item has one parent item and can have many child items. So when you're looking to manipulate a menu item within a sidebar panel, you will need to first retrieve the parent menu item, which in the case above is "My Account", followed by the "Billing Information" menu item which is a child within that.</div>
+<div class="docs-alert-info">
+The client area's sidebar menu system is defined in a tree structure. Each menu item has one parent item and can have many child items. So when you're looking to manipulate a menu item within a sidebar panel, you will need to first retrieve the parent menu item, which in the case above is '''Account''', followed by the '''Account Details''' menu item which is a child within that.
+</div>
 ==Changing the Text Label of a Sidebar Item==
@@ Line 85: / Line 87: @@
 ==Adding an Additional Sidebar Menu Item==
-To add an additional item to a menu, we must first check that the sidebar exists on the particular page before speciying  You can add additional menu items as follows:
+Before adding an item to a menu, check that the sidebar exists on that specific page. You can then add more menu items using code like the following example:
 <source lang="php">
 <?php
 use WHMCS\View\Menu\Item as MenuItem;
 add_hook('ClientAreaPrimarySidebar', 1, function (MenuItem $primarySidebar)
 {
-	if (!is_null($primarySidebar->getChild('My Account'))) {
+    if (!is_null($primarySidebar->getChild('My Account'))) {
-		$primarySidebar->getChild('My Account')
+        $primarySidebar->getChild('My Account')
-	->addChild('Mailing List Subscription Prefs')
+    ->addChild('Mailing List Subscription Prefs')
-		->setLabel('Subscription Preferences')
+        ->setLabel('Subscription Preferences')
-		->setUri('subscriptionprefs.php')
+        ->setUri('subscriptionprefs.php')
-		->setOrder(100);
+        ->setIcon('fa-user')
-	}
+        ->setOrder(100);
+    }
 });
 </source>
+== Custom Actions in the Service Details Sidebar Menu ==
+In WHMCS 8.5 and later, you can use the <tt>CustomActions</tt> server module function to add items to the server details sidebar menu. The item will perform a set function and then redirect the user to a specified URL.
+* For more information about custom actions, see [https://developers.whmcs.com/provisioning-modules/custom-actions/ our Developer Documentation].
+* You can also use this to add custom actions to [[Working With Client Area Home Page Panels|Client Area Home Page panels]].
 ==Hiding/Removing a Sidebar Menu Item==
@@ Line 116: / Line 126: @@
 add_hook('ClientAreaPrimarySidebar', 1, function(MenuItem $primarySidebar)
 {
-     $primarySidebar->getChild('My Account')
+     if(!is_null($primarySidebar->getChild('My Account')) && !is_null($primarySidebar->getChild('My Account')->getChild('Billing Information'))){
-        ->removeChild('Billing Information');
+    $primarySidebar->getChild('My Account')->removeChild('Billing Information');
+    }
+});
+</source>
+==Manipulate a Sidebar Menu Item by Name==
+You can also manipulate a menu item by name with the '''ClientAreaSidebars''' hook point. The following code would check to see which sidebar the element belongs to, and then allow you to act on it. In this example by removing it:
+<source lang="php">
+<?php
+use WHMCS\View\Menu\Item as MenuItem;
+add_hook('ClientAreaSidebars', 1, function() {
+    $primarySidebar = Menu::primarySidebar();
+    $secondarySidebar = Menu::secondarySidebar();
+    $id = 'Client Contacts';
+    if ($primarySidebar && !is_null($primarySidebar->getChild($id))) {
+        $objectToWorkWith = $primarySidebar->removeChild($id);
+    } elseif ($secondarySidebar && !is_null($secondarySidebar->getChild($id))) {
+        $objectToWorkWith = $secondarySidebar->removeChild($id);
+    }
+    if ($objectToWorkWith) {
+        $objectToWorkWith->removeChild($id);
+    }
 });
 </source>

Documentation