Difference between revisions of "Client Area Navigation Menus Cheatsheet"

Latest revision as of 14:09, 31 May 2022

The following guide is designed to provide some copy & paste ready code samples for common customisations performed to the dynamic client area navigation 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.

Finding a Menu Item Name

Every 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 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 you can manipulate it in the following ways.

The client area's navigation menu 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 dropdown, 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 Menu Item

All 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('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    $navItem = $primaryNavbar->getChild('Support');
    if (is_null($navItem)) {
        return;
    }

    $navItem = $navItem->getChild('Announcements');
    if (is_null($navItem)) {
        return;
    }

    $navItem->setLabel('Custom Title 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 Menu 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('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    $navItem = $primaryNavbar->getChild('Support');
    if (is_null($navItem)) {
        return;
    }

    $navItem = $navItem->getChild('Announcements');
    if (is_null($navItem)) {
        return;
    }

    $navItem->setUri('https://www.example.com/3rdpartyblogsystem');

});

Re-arranging Menu Items

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

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    $navItem = $primaryNavbar->getChild('Support');
    if (is_null($navItem)) {
        return;
    }

    $navItem = $navItem->getChild('Announcements');
    if (is_null($navItem)) {
        return;
    }

    $navItem->setOrder(1);

});

The following helpers are also available:

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

Adding a Menu Item

You can add a new link to the primary navigation as follows:

<?php
#adding Menu Item to primaryNavbar
use WHMCS\View\Menu\Item as MenuItem;
add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    $primaryNavbar->addChild('Menu Name')
        ->setUri('https://www.example.com/')
        ->setOrder(70);
});

Adding an Additional Child Menu Item

You can add additional menu items as follows:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    if (!is_null($primaryNavbar->getChild('Support'))) {
        $primaryNavbar->getChild('Support')
            ->addChild('Emergency Contacts', array(
                'label' => 'Emergency Contacts',
                'uri' => 'emergency.php',
                'order' => '100',
            ));
    }
});

To have your menu item use a language file text string for the display label, you can use the Lang::trans method as demonstrated below:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    if (!is_null($primaryNavbar->getChild('Support'))) {
        $primaryNavbar->getChild('Support')
            ->addChild('Emergency Contacts', array(
                'label' => Lang::trans('emergencyContacts'),
                'uri' => 'emergency.php',
                'order' => '100',
            ));
    }
});

To add a menu item conditionally based on client login status, you can do that using menu context as follows:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    $client = Menu::context('client');

    // only add menu item when no client logged in
    if (is_null($client)) {
        $primaryNavbar->addChild('Example')
            ->setUri('https://www.example.com/')
            ->setOrder(100);
    }
});

Hiding/Removing a Menu Item

You can remove a menu item as follows:

<?php
use WHMCS\View\Menu\Item as MenuItem;
add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    if (!is_null($primaryNavbar->getChild('Network Status'))) {
        $primaryNavbar->removeChild('Network Status');
    }
});

You can remove a child menu item as follows:

<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
    if (!is_null($primaryNavbar->getChild('Support'))) {
        $primaryNavbar->getChild('Support')->removeChild('Announcements');
    }
});

Open Links In A New Tab

You can open links in a new browser window using the setAttribute method. For example, if you are using an external system to control our knowledgebase, you could use the following code:

<?php
use WHMCS\View\Menu\Item as MenuItem;
add_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)
{
$navItem = $primaryNavbar->getChild('Knowledgebase');
if (is_null($navItem)) {
	return;
}
$navItem->setUri('https://www.example.com/3rdpartyknowledgebasesystem');
$navItem->setAttribute("target", '_blank');
});