Working With Client Area Home Page Panels

From WHMCS Documentation

Like the Client Area's navigation and sidebars, the panels displayed on the Client Area homepage are based on a tree structure of menu item objects. These panels display on the homepage to present quick information like overdue invoices or links to active services to a client after they log in. Modifying these panels is very similar to modifying navbars and side bars.

Panel Structure

The Client Area's panels have an invisible root item. Each panel is a child of that invisible root item. Many of these panels render their own child items as lists of links inside the panel.

  • root item
    • panel item
      • line item
      • line item
      • line item
    • panel item
      • line item
      • line item
    • panel item

Panel Layout

Desktop Mode

The WHMCS 8.5 Client Area homepage panel layout in desktop mode
When viewed in desktop mode, typically on desktop web browsers, most client area homepage panels render in two columns. In WHMCS 8.5 and later, it is also possible to create panels that span both columns.
  • For single-column panels, odd numbered panels are rendered on the left column and even numbered panels are rendered on the right column.
  • Panels that span both columns will render above the two-column layout, separately from the array of panels. Because of this, if a two-column panel is present, a single-column even numbered panel can become an odd-numbered panel.

Responsive Mode

The WHMCS 8.5 Client Area homepage panel layout in responsive mode
Responsive mode activates when the Client Area displays on a smaller screen, typically a phone or tablet. Responsive mode renders all panels in a single column with the left column over the right column. Odd-numbered panels display above even-numbered panels in responsive mode.

Differences With Navigation And Sidebar Menu Items

When it renders, a Client Area homepage panel resembles a panel in the sidebar. It uses the same underlying structure as the menu item objects that render the sidebar with a few changes:

Linking

A homepage panel's label is not a clickable link. Setting a URI on a homepage panel has no effect in WHMCS.

Custom Colors

Panels can render in a custom color when you define the color menu item attribute.

The following colors are available:

  • gold
  • green
  • red
  • blue
  • orange
  • pink
  • purple
  • lime
  • magenta
  • teal
  • turquoise
  • emerald
  • amethyst
  • wet-asphalt
  • midnight-blue
  • sun-flower
  • pomegranate
  • silver
  • asbestos

Optional Button

Each homepage panel has an optional button that renders to the right of the panel's label and badge.

Define the following menu item extras to render a button in a homepage panel:

  • btn-link — The URL to load in the user's web browser when the viewer clicks the button.
  • btn-text — The text within the button.
  • btn-icon — An optional Font Awesome icon to display to the left of the button's text.
  • colspan — In WHMCS 8.5 and later, an optional Boolean value that causes the panel to span both columns.

Default Panels

The following panels are defined by default. Hooks can register additional panels as well as interact with the default ones, so there is no guarantee that these panels will be visible or use this display order.

In addition, most of the panels are conditional and require the user to have the appropriate permissions.

Name Order Required Permission Conditions for Display
Unpaid Invoices 10 Invoices At least one unpaid invoice with no overdue invoices
Overdue Invoices 10 Invoices At least one overdue invoices
Domains Expiring Soon 50 Manage Domains At least one domain expiring within 45 days
Active Products/Services 100 Manage Products None
Recent Support Tickets 150 Support Tickets None
Register a New Domain 200 Orders Domain registration enabled
Your Files 250 None At least one file associated with the client's account
Affiliate Program 300 Affiliate An active affiliate account
Recent News 500 None None

Interacting With Homepage Panels

You can use WHMCS’ add_hook() function to call custom code when WHMCS is rendering homepage panels.

  • The ClientAreaHomepagePanels hook allows you to manipulate the Client Area homepage's panels.
    • Call this hook before you assign the panel object to the view template.
    • This hook passes the Client Area home panel's root item to the hook function.
  • For more information about using the hook system and supported hook functions, see our Developer Documentation.

In WHMCS 8.5 and later, you can use the CustomActions server module function to define items that perform a set function and then redirect the user to a specified URL.

  • Customers can invoke items from within the Client Area.
  • Use this to specfically add items to the My Active Products/Services panel in the Client Area home page.
  • For more information on using custom actions, see our Developer Documentation.
  • You can also use this to add custom actions to Client Area service sidebar menus.

Examples

Add a panel to the homepage

The WHMCS 6 client area homepage with a custom local temperatures panel highlighted.
This example makes use of a free third-party service that is not part of WHMCS. WHMCS cannot guarantee the state of this service and uses it for example purposes only.

This example uses the ClientAreaHomepagePanels hook and the menu item's addChild() and moveToFront() methods. The WHMCS\User\Client class contains the information to query for this example's weather data. This calls the United States National Weather Service's National Digital Forecast Database web service and requires SOAP support in your PHP installation. It also uses the Carbon library for date manipulation and display. The Carbon library is bundled with WHMCS 6.0 and later.

To add this panel to the client area homepage:

  1. Translate the logged in user's ZIP code into a latitude-longitude pair.
  2. Send the user's latitude-longitude pair to the NDFD service to retrieve their local forecast.
  3. Add a Local Temperatures child panel to the homepage panels list with today's temperatures in the panel's body HTML.
  4. Add child items to the panel for the next five days of temperatures. WHMCS will display these temperatures in a list inside the panel.
  5. Move the local temperatures to the beginning so that they display first.

Create the includes/hooks/clientWeatherPanel.php file in your WHMCS installation and enter the code below. WHMCS will parse the file and hook when the page loads. It will run the hook function when the client visits the homepage after logging in. 

<?php
 
use Carbon\Carbon;
use WHMCS\Authentication\CurrentUser;
use WHMCS\View\Menu\Item;
 
add_hook('ClientAreaHomepagePanels', 1, function (Item $homePagePanels)
{
    /** @var \WHMCS\User\Client $currentUser */
    $currentUser = CurrentUser::client();
    $today = Carbon::now()->startOfDay();
 
    // Connect to the United States' National Weather Service.
    // See http://graphical.weather.gov/xml/ for more information.
    $soapClient = new SoapClient('http://graphical.weather.gov/xml/DWMLgen/wsdl/ndfdXML.wsdl');
 
    // The weather API takes a latitude/longitude pair as input. Translate the
    // current user's zip code into a coordinate pair.
    $response = simplexml_load_string($soapClient->LatLonListZipCode($currentUser->postcode));
    list ($latitude, $longitude) = explode(',', $response->latLonList);
 
    // Query for the weather forecast and turn it into display data.
    $response = simplexml_load_string($soapClient->NDFDGen($latitude, $longitude, 'glance'));
    $maximumTemperatures = (array)$response->data->parameters->temperature[0]->value;
    $minimumTemperatures = (array)$response->data->parameters->temperature[1]->value;
 
    // Build the new temperature panel by adding a child panel to the panel
    // list.
    $todaysMaximum = $maximumTemperatures[0];
    $todaysMinimum = $minimumTemperatures[0];
 
    $weatherPanel = $homePagePanels->addChild('local temperatures', array(
        'label' => 'Local Temperatures',
        'icon' => 'fa-cloud',
        'extras' => array(
            'color' => 'blue',
        ),
        'bodyHtml' => "<p>Today's temperature in {$currentUser->city}: {$todaysMinimum}°F / {$todaysMaximum}°F</p>",
    ));
 
    // Add the 5-day temperature forecast as child items to the panel so WHMCS
    // can present them nicely in a list.
    for ($i = 1; $i <= 5; $i++) {
        $day = $today->addDays(1);
        $minimumTemperature = $minimumTemperatures[$i];
        $maximumTemperature = $maximumTemperatures[$i];
 
        $weatherPanel->addChild($day->format('l, F j'), array(
            'label' => $day->format('l, F j'),
            'icon' => 'fa-angle-double-right',
            'badge' => "{$minimumTemperature}°F / {$maximumTemperature}°F",
            'order' => $i,
        ));
    }
 
    // Finally, move the panel to the beginning of the panel list so it's
    // displayed first.
    $weatherPanel->moveToFront();
});

Add a promotional offer panel

The WHMCS 6 client area homepage in responsive mode with custom special offer panel highlighted.
Like the previous example, this example uses the ClientAreaHomepagePanels hook and the menu item's addChild() method. Unlike the previous example, it doesn't list child items but will use a panel's body HTML and custom button in the corner.

To add this panel to the client area homepage:

  1. Add a child panel to the homepage panels list that has the the following extras:
    • A btn-link extra containing a link to the special promo.
    • A btn-text extra containing the text of the button.
  2. Define body and footer HTML in the panel to make the promotion conform to WHMCS' look and feel.
  3. Set the order to 20 to place it after the default unpaid and overdue invoice panels.

Create the includes/hooks/specialOfferPanel.php file in your WHMCS installation and enter the code below. As with the previous example, WHMCS will parse the file and hook when the page loads and will run the hook function when the client visits the homepage after logging in. 

<?php
 
use WHMCS\View\Menu\Item;
 
add_hook('ClientAreaHomepagePanels', 1, function (Item $homePagePanels)
{
    $thankYouMessage = <<<EOT
<p>Thanks for beta testing our latest offerings! To show our appreciation we'd
like to provide next month of service <strong>on the house</strong>.</p>
EOT;
 
    // Add a homepage panel with a link to a free month promo and mode it to the
    // front of the panel list.
    $homePagePanels->addChild('thanks', array(
        'label' => 'Thanks for the help!',
        'icon' => 'fa-thumbs-up',
        'order' => 20,
        'extras' => array(
            'color' => 'gold',
            'btn-link' => 'https://example.org/free-month-promo',
            'btn-text' => 'Redeem Your Free Month',
            'btn-icon' => 'fa-arrow-right',
        ),
        'bodyHtml' => $thankYouMessage,
        'footerHtml' => 'Act fast! This offer expires soon!',
    ));
});

Modifying an existing panel

Another common item is to want to change a link button and its text in a home panel panel (for example: if you want to link to a third party ticket system you already have in place.

Create the includes/hooks/recentTicketsPanel.php file in your WHMCS installation and enter the code below. As with the previous example, WHMCS will parse the file and hook when the page loads and will run the hook function when the client visits the homepage after logging in. 

<?php
  
// This hook will adjust the button in the homepage panels. You have two
// different options of setExtra() or setExtras(). Use of setExtras() requires
// passing all 'extra' related vars through the array.
  
use WHMCS\View\Menu\Item;
  
add_hook('ClientAreaHomepagePanels', 1, function (Item $homePagePanels) {
    $recentTicketsPanel = $homePagePanels->getChild('Recent Support Tickets');
      
    if (!is_null($recentTicketsPanel)) {
        $recentTicketsPanel->setExtras(
            [
                'color' => 'amethyst',
                'btn-text' => 'New Name Here',
                'btn-link' => 'http://newlinkgoes.here',
                'btn-icon' => 'fa-thumbs-o-down',
            ]
        );
    }
});

Rearranging an existing panel

You may wish to change the order in which a panel appears within the Client Area.

Create the includes/hooks/rearrangeRegisterDomainPanel.php file in your WHMCS installation and enter the code below. As with previous examples, WHMCS will parse the file and hook when the page loads and will run the hook function when the client visits the homepage after logging in. 

<?php
   
// This hook will rearrange the Register a New Domain panel
// to be the first panel displayed in the client area
 
use WHMCS\View\Menu\Item;
    
add_hook('ClientAreaHomepagePanels', 1, function (Item $homePagePanels) {
    if (!is_null($homePagePanels->getChild('Register a New Domain'))) {
        $homePagePanels->getChild('Register a New Domain')
        ->setOrder(0);
    }
});

Removing an existing panel

You may wish to remove a panel from the client area.

Create the includes/hooks/removeRegisterDomainPanel.php file in your WHMCS installation and enter the code below. As with previous examples, WHMCS will parse the file and hook when the page loads and will run the hook function when the client visits the homepage after logging in. 

<?php
   
// This hook will remove the Register a New Domain panel from the client area
 
use WHMCS\View\Menu\Item;
    
add_hook('ClientAreaHomepagePanels', 1, function (Item $homePagePanels) {
    if (!is_null($homePagePanels->getChild('Register a New Domain'))) {
        $homePagePanels->removeChild('Register a New Domain');
    }
});

Creating a two-column panel

You may wish to create a two-column panel above the one-column panel layout, or convert an existing panel.

To do this, create the includes/hooks/fullWidthRegisterDomainPanel.php file in your WHMCS installation and enter the code below. WHMCS will parse the file and hook when the page loads and will run the hook function when the client visits the homepage after logging in. 

<?php
 
// This hook causes the Register a New Domain panel to be a two-column panel.
 
use WHMCS\View\Menu\Item;
 
add_hook('ClientAreaHomepagePanels', 1, function (Item $homePagePanels) {
 if (!is_null($homePagePanels->getChild('Register a New Domain'))) {
 $homePagePanels->getChild('Register a New Domain')->setExtra('colspan', true);
 }
});
Retrieved from "https://docs.whmcs.com/index.php?title=Working_With_Client_Area_Home_Page_Panels&oldid=33113"