Working With Client Area Home Page Panels

From WHMCS Documentation

Revision as of 17:31, 9 February 2017 by Lawrence (talk | contribs) (→‎Modifying an existing panel)

Like the client area's navigation and sidebars, the panels displayed on the client area home page are based on a tree structure of menu item objects. These panels are displayed on the home page to present quick information to a client after they log in, such as overdue invoices, links to active products and services, and domains that are soon to expire. Like the client area's navigation and sidebars, these panels can be modified programmatically. Working with these panels is nearly identical 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 panels in turn have their own child items that are rendered 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 6.0 client area homepage panel layout in desktop mode
When viewed in desktop mode, typically on desktop web browsers, client are homepage panels are rendered in two columns. Odd numbered panels are rendered on the left column and even numbered panels are rendered on the right column.

Responsive Mode

The WHMCS 6.0 client area homepage panel layout in responsive mode
Responsive mode is activated when the client ares is viewed on a smaller screen, typically on a phone or tablet. Responsive mode renders all panels in a single column, with the left column placed over the right column. This means that odd numbered panels are displayed above even numbered panels in responsive mode.

Differences With Navigation And Sidebar Menu Items

File:Client area panel item.png
A client area home page panel represented as menu item properties
When rendered, a client area home page panel resembles a panel in the sidebar. It uses the same underlying structure as the menu item objects that render the sidebar, though with a number of changes:

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

Panels can be rendered in a custom color to give it a unique effect. Define the color menu item attribute to set this color. 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

Finally, a home page panel has an optional button rendered to the right of the panel's label and badge. Define the following menu item extras to render a button in a home page panel:

  • btn-link: The URL to load in the user's web browser when the button is clicked.
  • btn-text: The text within the button.
  • btn-icon: An optional Font Awesome icon to display to the left of the button's text.

Default Panels

The following panels are defined by default. Please note that 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 necessarily in the given display orders.

In addition, most of the panels are conditional. They only display when certain conditions are met in addition to the user having 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 30 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 Home Page Panels

WHMCS 6.0 introduce a hook to allow manipulation of the client area home page's panels. Use WHMCS’ add_hook() function to call custom code when WHMCS is ready to render these panels.

  • ClientAreaHomepagePanels
    • Called prior to assigning the panel object to the view template.
    • Passes the client area home panels' root item to the hook function.

Examples

Add a local temperature panel to the homepage

The WHMCS 6 client area home page with a custom local temperatures panel highlighted.
Please note that this example makes use of a free third party service unrelated to WHMCS. WHMCS cannot guarantee the state of this service and uses it for example purposes only.

The powers that be at your hosting company have decided that they want to be their clients' single stop for everything and want to start providing a seamless general portal experience in addition to quality hosting. They feel that showing a simple temperature forecast after the user logs in is a good start to achieving it. Luckily, WHMCS provides a way to easily add this to the interface.

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 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 version 6. To add this panel to the client area home page we must:

  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 child panel to the home page panels list that has the label "Local Temperatures" and has 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 it's displayed first.

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

<?php

use Carbon\Carbon;
use WHMCS\User\Client;
use WHMCS\View\Menu\Item;

add_hook('ClientAreaHomepagePanels', 1, function (Item $homePagePanels)
{
    /** @var \WHMCS\User\Client $currentUser */
    $currentUser = Client::find($_SESSION['uid']);
    $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}&deg;F / {$todaysMaximum}&deg;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}&deg;F / {$maximumTemperature}&deg;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 home page in responsive mode with custom special offer panel highlighted.
After a lengthy beta period, your company has just released the latest version of its flagship product. The users love it, and the orders are rolling in. The public beta period was so successful that management wants to offer a free month of the service to all existing clients. The promo page is ready to go, so all that's left is to inform the users. The sales team wants it to show up after any unpaid or overdue invoice notices. There's a business to run, after all. Thankfully WHMCS provides an easy way to let the users know about the special offer right after they log in.

Like the previous example, this example uses the ClientAreaHomepagePanels hook and the menu item's addChild() method. Unlike the previous examples though it doesn't need a list of child items, but it will use a panel's body HTML and custom button in the corner. To add this panel to the client area home page we must:

  1. Add a child panel to the home page 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 on page load and will run the hook function when the client visits the home page 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 on page load and will run the hook function when the client visits the home page after logging in. 

<?php
 
// This hook will adjust the button in the home page 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',
            ]
        );
    }
});
Retrieved from "http://3.17.75.209/index.php?title=Working_With_Client_Area_Home_Page_Panels&oldid=22062"