View source for Working With Client Area Home Page Panels

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 ===
 
[[Image:85DesktopClientPanels.png|thumb|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 ===
 
[[Image:85ResponsiveClientPanels.png|thumb|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.
 
<div style="clear: both"></div>
 
== 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 <tt>color</tt> 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. 
 
<div style="clear: both"></div>
 
== 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.
 
{| class="wikitable"
|-
! 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 the <tt>ClientAreaHomepagePanels</tt> hook 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 panels' root item to the hook function.
 
Use WHMCS’ <tt>add_hook()</tt> function to call custom code when WHMCS is ready to render these panels.
 
== Examples ==
 
=== Add a panel to the homepage ===
 
[[Image:85-6-LocalTempsHomePanel.png|thumb|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 <tt>addChild()</tt> and <tt>moveToFront()</tt> methods. The <tt>WHMCS\User\Client</tt> class contains the information to query for this example's weather data. This calls the United States National Weather Service's [http://graphical.weather.gov/xml/ National Digital Forecast Database web service] and requires [http://php.net/manual/en/book.soap.php SOAP] support in your PHP installation. It also uses the [https://github.com/briannesbitt/Carbon 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:
 
# Translate the logged in user's ZIP code into a latitude-longitude pair.
# Send the user's latitude-longitude pair to the NDFD service to retrieve their local forecast.
# Add a ''Local Temperatures'' child panel to the homepage panels list with today's temperatures in the panel's body HTML.
# Add child items to the panel for the next five days of temperatures. WHMCS will display these temperatures in a list inside the panel.
# Move the local temperatures to the beginning so that they display first.
 
Create the <tt>includes/hooks/clientWeatherPanel.php</tt> 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.
 
<div style="clear: both"></div>
 
<syntaxhighlight lang="php">
<?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();
});
</syntaxhighlight>
 
=== Add a promotional offer panel ===
 
[[Image:86RedeemOfferHomePanel.png|thumb|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 <tt>addChild()</tt> 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:
 
# 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.
# Define body and footer HTML in the panel to make the promotion conform to WHMCS' look and feel.
# Set the order to 20 to place it after the default unpaid and overdue invoice panels.
 
Create the <tt>includes/hooks/specialOfferPanel.php</tt> 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.
 
<div style="clear: both"></div>
 
<syntaxhighlight lang="php">
<?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!',
    ));
});
</syntaxhighlight>
 
=== 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 <tt>includes/hooks/recentTicketsPanel.php</tt> 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.
 
<div style="clear: both"></div>
 
<syntaxhighlight lang="php">
<?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',
            ]
        );
    }
});
</syntaxhighlight>
 
=== Rearranging an existing panel ===
 
You may wish to change the order in which a panel appears within the Client Area.
 
Create the <tt>includes/hooks/rearrangeRegisterDomainPanel.php</tt> 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.
<div style="clear: both"></div>
<syntaxhighlight lang="php">
<?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);
    }
});
</syntaxhighlight>
 
=== Removing an existing panel ===
 
You may wish to remove a panel from the client area.
 
Create the <tt>includes/hooks/removeRegisterDomainPanel.php</tt> 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.
<div style="clear: both"></div>
<syntaxhighlight lang="php">
<?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');
    }
});
</syntaxhighlight>
 
=== 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 <tt>includes/hooks/fullWidthRegisterDomainPanel.php</tt> 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.
 
<syntaxhighlight lang="php">
<?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);
 }
});
</syntaxhighlight>
No results found.