WHMCS Documentation - User contributions [en]

Editing Client Area Menus

2015-09-22T20:24:15Z

Kevin:

WHMCS version 6 introduces a programmatic way to interact with the client area navigation and sidebars through hooks and modules.

<div class="docs-alert-warning"><strong>In a hurry?</strong> We have made available two guides containing copy & paste ready code samples for common customisations performed to the dynamic navigation and sidebar menus.
* [[Client Area Navigation Menus Cheatsheet]]
* [[Client Area Sidebars Cheatsheet]]
</div>

=Menu structure=

The client area's navigation and sidebars are defined in a tree structure of [http://docs.whmcs.com/classes/classes/WHMCS.View.Menu.Item.html menu item objects]. Each menu item has one parent item and can have many child items. The only menu item with no parent an invisible root item that is not displayed on the page.

==Navigation bars==

Navigation bars consist of the invisible menu root with children representing every item displayed in the navigation bar. Each of these items may have their own child items. These child items are rendered as that navigation bar item's dropdown menu.

* ''Navigation bar root Item''
** navigation item
** navigation item
*** dropdown item
** navigation item
*** dropdown item
*** dropdown item
*** dropdown item
** navigation item

Navigation bars are displayed on every page in the client area, but their contents may change if a client is logged in or not. For instance, the navigation bar may show login and password recovery links if a user isn't logged in.

==Sidebars==

Like the navigation bar, the sidebars in WHMCS begin with an invisible menu root, but each child represents an individual panel in the side bar. Each panel item is rendered as an item within the panel in the WHMCS client area.

* ''Sidebar root Item''
** panel
*** panel item
*** panel item
*** panel item
** panel
*** panel item
*** panel item
** panel
*** panel item
*** panel item
*** panel item

Sidebars help provide context for the data displayed on the page. Different pages in the client area may have different sidebar items. For example, a page to view an account may contain sidebar links to view that client’s open tickets or unpaid invoices.

=Menu layout=

==Desktop mode==

[[Image:Desktop mode.png|thumb|The WHMCS 6.0 client area layout in desktop mode]] There are two navigation bars in WHMCS’ client area. The primary navigation bar contains the bulk of the menu and floats to the left of the secondary navigation bar. The secondary navigation bar contains user-specific items and changes if a client is logged in to WHMCS. When a client is not logged in then the secondary navigation contains a login link, and when a client is logged in then the secondary menu contains links to the client’s account.

Likewise there are two sidebars on every client area page. The primary sidebar is displayed above the secondary side bar on the left side of the page. Sidebar content varies per page, though the primary sidebar typically displays information directly relevant to the page content while the secondary sidebar usually contains more general links.

<div style="clear: both"></div>

==Responsive mode==

[[Image:Responsive mode.png|thumb|The WHMCS 6.0 client area layout in responsive mode]] Responsive mode is activated when WHMCS’ client area is viewed on a smaller screen device such as a phone or tablet. WHMCS rearranges the page layout in responsive mode for best display on mobile devices.

In responsive mode the primary and secondary navigation bars are displayed above the primary sidebar, followed by the page’s content with the secondary sidebar displayed at the bottom of the page.

<div style="clear: both"></div>

=Menu items=

Menu items are modeled in code by the [http://docs.whmcs.com/classes/classes/WHMCS.View.Menu.Item.html <tt>\WHMCS\View\Menu\Item</tt>] class. These objects contain all of the information needed to render that menu item within a template, including their parent and child menu item relationships. Menu items can have the following aspects:

* A single parent item
* Multiple optional child items
* A name used to internally refer to the menu item
* A label to display when the item is rendered to the page. If no label is defined, then WHMCS render's the menu item's name
* A URI to link to when the user clicks or taps on a menu item
* An optional icon displayed to the left of the label. WHMCS has access to both the [http://getbootstrap.com/components/#glyphicons Glyphicons] and [http://fortawesome.github.io/Font-Awesome/ Font Awesome] libraries.
* An optional badge displayed to the right of the label, usually used for contextual information, such as the number of tickets in a status next to that statuses' name
* The order that a menu item is displayed in its parent's list of children.

=Menu item arrangement=

==Navigation bars==

[[Image:Navbar item.png|thumb|A client area navigation bar item represented as menu item properties.]] This diagram represents an individual menu item in the navigation bars. All of the menu item’s children are rendered as dropdown menu items. All menu items are rendered with icons to the left of a link to the menu item’s URI followed by the menu item’s badge.

<div style="clear: both"></div>

==Sidebars==

[[Image:Sidebar panel.png|thumb|A client area sidebar panel represented as menu item properties.]] This diagram represents an individual menu item in the sidebars. Unlike the navigation bars this menu item renders a panel in the side bar. Items in the panel rendered by the menu item’s children. Note how body and footer HTML content are also rendered around sidebar panel items. All menu items are rendered with icons to the left of a link to the menu item’s URI followed by the menu item’s badge.

<div style="clear: both"></div>

=Interacting with menus=

==Hooks==

WHMCS 6.0 introduces a number of hooks to allow menu interaction before they’re sent to the template renderer. Use WHMCS’ <tt>add_hook()</tt> function to call custom code when WHMCS reaches these hook points during page generation.

* '''ClientAreaPrimaryNavbar'''
** Called prior to rendering navigation bars.
** Passes the primary navigation bar object to the hook function.
* '''ClientAreaSecondaryNavbar'''
** Called prior to rendering navigation bars.
** Passes the secondary navigation bar object to the hook function.
* '''ClientAreaNavbars'''
** Called prior to rendering navigation bars.
** Passes no parameters to the hook function.
* '''ClientAreaPrimarySidebar'''
** Called prior to rendering sidebars.
** Passes the primary side bar object to the hook function.
* '''ClientAreaSecondarySidebar'''
** Called prior to rendering sidebars.
** Passes the secondary side bar object to the hook function.
* '''ClientAreaSidebars'''
** Called prior to rendering sidebars.
** Passes no parameters to the hook function

==Direct Access==

WHMCS allows direct manipulation of menu objects outside the hooks system for modules and other custom code that don’t use the hooks system. The built-in <tt>Menu</tt> class is an alias to an object repository that can retrieve all of WHMCS’ menu objects. Please note that if the menu isn’t generated by the page yet then an empty menu structure may exist that is overwritten by normal page generation. WHMCS recommends using the hooks system to interact with menus.

The <tt>Menu</tt> class has four static methods to retrieve menus:

* ''Item'' '''Menu::primaryNavbar()'''
** Retrieve the primary navigation bar.
* ''Item'' '''Menu::secondaryNavbar()'''
** Retrieve the secondary navigation bar.
* ''Item'' '''Menu::primarySidebar()'''
** Retrieve the primary sidebar.
* ''Item'' '''Menu::secondarySidebar()'''
** Retrieve the secondary sidebar.

WHMCS employs a number of pre-built sidebars in its built-in pages. These side bars are available to hook and module developers through the <tt>Menu::PrimarySidebar()</tt> and <tt>Menu::SecondarySidebar()</tt> methods. Call either of these methods with the name of the sidebar as the first parameter to retrieve the pre-built sidebar. WHMCS will build the side bar if it isn't already defined. See the table below for the currently defined pre-built sidebars and which pages they are used on.

==Context==

WHMCS’ menus, especially the sidebars, render information specific to the page in the client area that’s being accessed by the user. For instance, client information is passed to the “my account” page and ticket information is passed to the “view ticket page”. This data is passed to menu item objects as context. Context can be any PHP object or data type. The <tt>Menu</tt> class has two static methods for setting and retrieving context items:

* ''void'' '''Menu::addContext(string $key, mixed $value)'''
** Add $value to the menu context at the key $key, overriding existing values.
* ''mixed|null'' '''Menu::context(string $key)'''
** Retrieve the menu context at $key or null if no context exists at the key.

{| class="wikitable"
|+ Pre-set sidebars used per page
|-
! Sidebar name
! Pages used on
! Context
|-
! affiliateView
|
* <tt>affiliates.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
|-
! announcementList
|
* <tt>announcements.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
* ''[[collection]] of [https://github.com/briannesbitt/Carbon \Carbon\Carbon]'': '''monthsWithAnnouncements'''
** The past ten months in which announcements have been published.
|-
! clientAddFunds
|
* <tt>clientarea.php?action=addfunds</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
|-
! clientRegistration
| <tt>register.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''[[collection]] of [http://docs.whmcs.com/classes/classes/WHMCS.User.Client.SecurityQuestion.html \WHMCS\User\Client\SecurityQuestion]'': '''securityQuestions'''
** The configured system security questions.
|-
! clientQuoteList
|
* <tt>clientarea.php?action=quotes</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
|-
! clientView
|
* <tt>clientarea.php</tt>
* <tt>clientarea.php?action=addcontact</tt>
* <tt>clientarea.php?action=changepw</tt>
* <tt>clientarea.php?action=contacts</tt>
* <tt>clientarea.php?action=creditcard</tt>
* <tt>clientarea.php?action=details</tt>
* <tt>clientarea.php?action=emails</tt>
* <tt>clientarea.php?action=security</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
|-
! rowspan="2" | domainList
|
* <tt>clientarea.php?action=domains</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
|-
| colspan="2" | If the <tt>q</tt> request variable is defined, then the client's associated domain counts in the primary sidebar are filtered to those domains whose names contain <tt>q</tt>'s value.
|-
! domainView
| style="white-space:nowrap" |
* <tt>clientarea.php?action=domaincontacts</tt>
* <tt>clientarea.php?action=domaindetails</tt>
* <tt>clientarea.php?action=domaindns</tt>
* <tt>clientarea.php?action=domainemailforwarding</tt>
* <tt>clientarea.php?action=domaingetepp</tt>
* <tt>clientarea.php?action=domainregisterns</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''[http://docs.whmcs.com/classes/classes/WHMCS.Domain.Domain.html \WHMCS\Domain\Domain]'': '''domain'''
** The domain that the client is viewing on the page.
|-
! rowspan="2" | downloadList
|
* <tt>dl.php</tt>
* <tt>downloads.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
* ''[[collection]] of [http://docs.whmcs.com/classes/classes/WHMCS.Download.Download.html \WHMCS\Download\Download]'': '''topFiveDownloads'''
** The five most downloaded files that are not hidden or in a hidden download category, ordered by number of downloads in descending order.
* ''[http://docs.whmcs.com/classes/classes/WHMCS.Download.Category.html \WHMCS\Download\Category]'': '''downloadCategory'''
** The download category the user is currently viewing.
|-
| colspan="2" | The ''topFiveDownloads'' and 'downloadCategory'' contexts are only passed to <tt>download.php</tt>.
|-
! invoiceList
|
* <tt>clientarea.php?action=invoices</tt>
* <tt>clientarea.php?action=masspay</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
|-
! networkIssueList
| <tt>serverstatus.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''array'': '''networkIssueStatusCounts'''
** A key/value pair of network issue statuses and the number of network issues with each status.
|-
! rowspan="2" | orderFormView
| <tt>cart.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''[[collection]] of [http://docs.whmcs.com/classes/classes/WHMCS.Product.Group.html \WHMCS\Product\Group]'': '''productGroups'''
** A WHMCS installation's configured product groups.
* ''int'': '''productGroupId'''
** The current ''gid'' GET parameter value.
* ''bool'': '''domainRegistrationEnabled'''
** Whether or not WHMCS is configured to register domains.
* ''bool'': '''domainTransferEnabled'''
** Whether or not WHMCS is configured to transfer domains.
* ''bool'': '''domainRenewalEnabled'''
** Whether or not WHMCS is configured to renew domains.
* ''string'': '''domain'''
** When configuring domain options, the name of the domain in the shopping cart.
* ''string'': '''currency'''
** The user's configured currency, or the system currency if no user is logged in. Eg: "USD", "GBP".
|-
| colspan="2" | Only the secondary sidebar is supported on <tt>cart.php</tt>.
|-
! rowspan="2" | serviceList
|
* <tt>clientarea.php?action=hosting</tt>
* <tt>clientarea.php?action=products</tt>
* <tt>clientarea.php?action=services</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
|-
| colspan="2" | If the <tt>q</tt> request variable is defined, then the client's associated service counts in the primary sidebar are filtered to those services whose domain names contain <tt>q</tt>'s value.
|-
! serviceUpgrade
|
* <tt>upgrade.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''[http://docs.whmcs.com/classes/classes/WHMCS.Service.Service.html \WHMCS\Service\Service]'': '''service'''
** The service currently being upgraded.
|-
! serviceView
|
* <tt>clientarea.php?action=cancel</tt>
* <tt>clientarea.php?action=productdetails</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''[http://docs.whmcs.com/classes/classes/WHMCS.Service.Service.html \WHMCS\Service\Service]'': '''service'''
** The service that the client is viewing on the page.
|-
! sslCertificateOrderView
|
* <tt>configuressl.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
* ''[http://docs.whmcs.com/classes/classes/WHMCS.Service.Service.html \WHMCS\Service\Service]|null'': '''service'''
** The service object representing the SSL certificate being ordered
* ''string'': '''orderStatus'''
** The current status of the SSL certificate order
* ''array'': '''displayData'''
** A key/value pair of additional SSL certificate data that is displayed on the page on step two of the order process
* ''int'': '''step'''
** The current step of the order process
|-
! rowspan="2" | support
| ''various''
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
|-
| colspan="2" | The support secondary sidebar is displayed when a contact does not have permission to perform an action in the client area.
|-
! supportKnowledgeBase
|
* <tt>knowledgebase.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in
* ''array'': '''knowledgeBaseTags'''
** An array of knowledge base tags and the number of articles with each tag.
|-
! rowspan="2" | ticketFeedback
|
* <tt>viewticket.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
|-
| colspan="2" | Only used on viewticket.php when a user is entering feedback for a recently closed ticket.
|-
! ticketList
|
* <tt>supporttickets.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''array'': '''ticketStatusCounts'''
** A key/value pair of ticket statuses with the number of tickets in that status.
|-
! ticketSubmit
|
* <tt>submitticket.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
|-
! ticketView
|
* <tt>viewticket.php</tt>
|
* ''[http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html \WHMCS\User\Client]|null'': '''client'''
** The client currently logged in, or <tt>null</tt> if no client is logged in.
* ''int'': '''ticketId'''
** The id number of the ticket the user is viewing.
|-
|}

=Examples=

==Add a social media panel to the end of the sidebar==

[[Image:Custom social media sidebar panel.png|thumb|The WHMCS 6 client area support secondary sidebar with a custom social media panel highlighted.]] Let's say we’re a hosting company who wants to better connect with our clients by using social media. The menu hooks introduced in WHMCS 6.0 allow us to insert links to our company’s Facebook, Twitter, and Google+ profiles directly into the interface. We’ll put them at the end of the secondary sidebar so they’re rendered last and won’t interrupt our users’ experience.

This example uses the '''ClientAreaSecondarySidebar''' hook and the menu item’s <tt>addChild()</tt>and <tt>moveToBack()</tt> methods. To add panel with links to the sidebar we must:

# Create a panel at the end of the sidebar.
# Retrieve the panel we just created.
# Add social media links to the panel.

Fortunately the Font Awesome library already has icons for all of these services. Create the <tt>includes/hooks/socialMediaPanel.php</tt> file in your WHMCS installation and enter the code below. Save the file and reload your WHMCS installation’s client area. WHMCS automatically loads all hooks the includes/hooks directory. The '''SecondarySidebar''' hook is registered with <tt>add_hook()</tt> and is consequently loaded every time WHMCS renders the secondary sidebar on page load.

<div style="clear: both"></div>

<syntaxhighlight lang="php">
<?php

use WHMCS\View\Menu\Item as MenuItem;

// Add social media links to the end of all secondary sidebars.
add_hook('ClientAreaSecondarySidebar', 1, function (MenuItem $secondarySidebar)
{
// Add a panel to the end of the secondary sidebar for social media links.
// Declare it with the name "social-media" so we can easily retrieve it
// later.
$secondarySidebar->addChild('social-media', array(
'label' => 'Social Media',
'uri' => '#',
'icon' => 'fa-thumbs-up',
));

// Retrieve the panel we just created.
$socialMediaPanel = $secondarySidebar->getChild('social-media');

// Move the panel to the end of the sorting order so it's always displayed
// as the last panel in the sidebar.
$socialMediaPanel->moveToBack();

// Add a Facebook link to the panel.
$socialMediaPanel->addChild('facebook-link', array(
'uri' => 'https://facebook.com/our-great-company',
'label' => 'Like us on Facebook!',
'order' => 1,
'icon' => 'fa-facebook',
));

// Add a Twitter link to the panel after the Facebook link.
$socialMediaPanel->addChild('twitter-link', array(
'uri' => 'https://twitter.com/ourgreatcompany',
'label' => 'Follow us on Twitter!',
'order' => 2,
'icon' => 'fa-twitter',
));

// Add a Google+ link to the panel after the Twitter link.
$socialMediaPanel->addChild('google-plus-link', array(
'uri' => 'https://plus.google.com/1234567890123456',
'label' => 'Add us to your circles!',
'order' => 3,
'icon' => 'fa-google-plus',
));
});
</syntaxhighlight>

==Add a special offer image and link to the top of the topmost sidebar==

[[Image:Custom panel body html highlighted.png|thumb|The WHMCS 6 client area announcements sidebar panel with a custom special offer highlighted.]] Your web host is doing amazing and to celebrate is offering a discount to all users. The marketing folks want a small image and message in the top of the first sidebar panel on every page that links to a page with the special offer.

This example uses the '''ClientAreaPrimarySidebar''' hook and the menu item’s <tt>getFirstChild()</tt> and <tt>setBodyHtml()</tt> methods. To add panel with links to the sidebar we must:

# Get the first panel from the primary sidebar.
# Set the panel’s body HTML.

Create the <tt>includes/hooks/specialOfferInSidebar.php</tt> file in your WHMCS installation and enter the code below. As with the previous example the new file and hook within the file is run on page load and adds the image and link to the topmost panel in the primary sidebar, no matter which page the client is accessing.

<div style="clear: both"></div>

<syntaxhighlight lang="php">
<?php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimarySidebar', 1, function (MenuItem $primarySidebar)
{
// The HTML for the link to the the special offer.
$specialOfferHtml = <<<EOT
<a href="//myawesomecompany.com/special-offer/">
<img src="/assets/img/catdeals.png" alt="Click here for amazing deals!">
Kitten says <strong><em>thanks</em></strong> for making us the best web host!
</a>
EOT;

// Add a link to the special to the first panel's body HTML. It will render
// above the panel's menu item list.
$firstSidebar = $primarySidebar->getFirstChild();
if ($firstSidebar) {
$firstSidebar->setBodyHtml($specialOfferHtml);
}
});
</syntaxhighlight>

==Move the “Contact Us” link to the secondary navigation bar and add more contact options==

[[Image:Custom navbar menu highlighted.png|thumb|The WHMCS 6 client area navbars with the Contact Us link moved to the secondary navbar with a custom dropdown menu.]] The graphic designer feels that our awesome hosting company’s WHMCS installation will more closely match the main site if the “Contact Us” link is moved to the right hand side of the installation’s navigation bars before the “Account” link. They also want a dropdown under the link with links specifically to email the sales team, call us, and provide a map to the company via Google Maps.

This example requires manipulating more than one menu bar. To do that we’ll use the '''ClientAreaNavbars''' hook and the <tt>Menu</tt> class to retrieve the primary and secondary navigation bars. We’ll use the menu item’s <tt>getChild()</tt>, <tt>removeChild()</tt>, <tt>addChild()</tt>, and <tt>moveToFront()</tt> methods and the static <tt>Menu::primaryNavbar()</tt> and <tt>Menu::secondaryNavbar()</tt> methods. Here’s what we’ll do:

# Save the “Contact Us” link from the primary navigation bar.
# Remove the “Contact Us” link from the primary navigation bar.
# Add an email link child to the “Contact Us” link.
# Add a phone link child to the “Contact Us” link.
# Add a map link child to the “Contact Us” link.
# Add the “Contact Us” link to the secondary navigation bar then move it to the beginning of the menu.

Create the <tt>includes/hooks/moveContactUsLink.php</tt> file in your WHMCS installation and enter the code below. As with the other examples this hook file is picked up on page load and rearranges the navigation bars with the appropriate dropdown items.

<div style="clear: both"></div>

<syntaxhighlight lang="php">
<?php

add_hook('ClientAreaNavbars', 1, function ()
{
// Get the current navigation bars.
$primaryNavbar = Menu::primaryNavbar();
$secondaryNavbar = Menu::secondaryNavbar();

// Save the "Contact Us" link and remove it from the primary navigation bar.
$contactUsLink = $primaryNavbar->getChild('Contact Us');
$primaryNavbar->removeChild('Contact Us');

// Add the email sales link to the link's drop-down menu.
$contactUsLink->addChild('email-sales', array(
'label' => 'Email our sales team',
'uri' => 'sales@my-awesome-company.com',
'order' => 1,
'icon' => 'fa-diamond',
));

// Add the call us link to the link's drop-down menu.
$contactUsLink->addChild('call-us', array(
'label' => 'Call us',
'uri' => 'tel:+18005551212',
'order' => 2,
'icon' => 'fa-mobile',
));

// Add the map to the company to the link's drop-down menu.
$contactUsLink->addChild('map', array(
'label' => '123 Main St. AnyTown, TX 11223, USA',
'uri' => 'https:\/\/maps.google.com/maps/place/some-map-data',
'order' => 3,
'icon' => 'fa-map-marker',
));

// Add the link and its drop-down children to the secondary navigation bar.
$secondaryNavbar->addChild($contactUsLink);

// Make sure the contact us link appears as the first item in the
// secondary navigation bar.
$contactUsLink->moveToFront();
});
</syntaxhighlight>

==Add support hours and a custom message to the sidebar on the submit ticket page==

[[Image:Custom support hours panel.png|thumb|The WHMCS 6 submit ticket page in responsive mode with support hours and a custom message in the primary sidebar.]] Your business has really taken off, and it's finally time to hire someone to help answer support tickets and sales inquiries. The new hire can't work 24 hours a day, 7 days a week, so it's time to implement official support hours. Your UX people feel that it's best to notify your users of these support hours on the submit ticket page, but only the submit ticket page. They'd like the hours at the top of the primary sidebar, so they're in plain view for the users. They'd also love it if we could notify the users that they can expect a reply from us soon or if they have to wait until the next business day.

Since the powers that be want this to appear at the top of the sidebars we'll manipulate the primary sidebar via the '''ClientAreaPrimarySidebar''' hook. We’ll use the menu item’s <tt>addChild()</tt>, <tt>moveToFront()</tt>, and <tt>setBodyHtml()</tt> methods to add the new panel. The special message to the user addresses the logged in user by first name. Every sidebar has a "client" context available which contains the record of the client that is logged in or ''null'' if no client is logged in. The <tt>Menu::context()</tt> method will retrieve the client record for us. If the client is logged in then we'll use the client object's <tt>firstName</tt> property to address the user by name. Version 6.0 uses the very helpful [https://github.com/briannesbitt/Carbon Carbon date library] internally. Carbon is available to third party developers, so we'll use it to determine if support is currently open. Here’s what we’ll do:

# Determine if the user is visiting <tt>submitticket.php</tt>.
# Add a "Support Hours" panel to the primary sidebar and move it to the front so it displays at the top.
# Create child items in the support hours panel saying when support is open and closed.
# Determine if support is currently open.
# If there is a user logged in then determine their first name.
# Assign the support hours' panel body HTML to a special message depending on the logged in user's first name and whether support is currently open.

Create the <tt>includes/hooks/addSupportHours.php</tt> file in your WHMCS installation and enter the code below. As with the other examples this hook file is picked up on page load and adds the custom panel and message to the primary sidebar before the submit ticket page renders.

<div style="clear: both"></div>

<syntaxhighlight lang="php">
<?php

use Carbon\Carbon;
use WHMCS\View\Menu\Item as MenuItem;

// Add a helpful support hours notice to the top of the sidebar on the submit
// ticket page.
if (App::getCurrentFilename() == 'submitticket') {
add_hook('ClientAreaPrimarySidebar', 1, function (MenuItem $primarySidebar)
{
// Create the support hours panel and make sure it's the first one
// displayed.
/** @var MenuItem $supportHours */
$supportHours = $primarySidebar->addChild('Support Hours');
$supportHours->moveToFront();

// Add hours to the panel.
$supportHours->addChild(
'<strong>Open</strong> 08:00-17:00 M-F',
array(
'icon' => 'fa-smile-o',
'order' => 1,
)
);
$supportHours->addChild(
'<strong>Closed</strong> Weekends',
array(
'icon' => 'fa-frown-o',
'order' => 2,
)
);

// Add a custom notice to the support hours panel with the logged in
// client's first name and a different message depending on whether
// support is open.
/** @var \WHMCS\User\Client $client */
$client = Menu::context('client');
$greeting = is_null($client)
? ''
: ", <strong>{$client->firstName}</strong>";

$now = Carbon::now();
$supportIsOpen = $now->isWeekday()
&& $now->hour >= 8
&& $now->hour <= 17;

$supportHours->setBodyHtml(
$supportIsOpen
? "Hi{$greeting}! We're open and will respond to your ticket soon!"
: "Don't worry{$greeting}! We will respond on the next business day. Sit tight!"
);
});
}
</syntaxhighlight>

Hooks

2015-07-09T04:26:27Z

Kevin:

==What is a Hook?==

Action Hooks allow you to add your own code to WHMCS that runs when specific events or actions occur inside the system. WHMCS has over 100 different hook points that you can tie custom code into, and more are being added with each new release.

The possibilities with hooks are endless, but some common examples of what you might use them for are:

*Registering users in another system when they signup via WHMCS
*Keeping user details in sync with third party applications
*Performing additional custom actions when an order is placed in WHMCS
*Sending notifications when certain events occur

{{Hook_Categories}}

There is also an [[Hooks:Alphabetical|alphabetical list]] of hooks available

==Creating a Hook==

Hooks work by defining a function, and then tieing that function into a hook point. Most custom hook functions are created as a standalone hook, and thus reside in the /includes/hooks/ folder. But hooks can also be part of modules (more details later on this).

Custom hook functions are usually passed variables when they are called, with the variables depending on the action the hook point relates to. Some hook points will also accept a return from your custom hook function, and that allows you to influence what the system does next from your custom code.

We recommend naming hook functions always starting with "hook_", followed by the filename, and then the particular action or task that hook is performing. For example "hook_filename_action" - "hook_forumsetup_addclient". This helps to ensure that no 2 hook functions from 2 separate developers ever conflict due to naming issues.

==Sample Code==

The best way to see how a hook works is with an example. So here's a sample hook function integrated into the Client Signup hook event:

<syntaxhighlight lang="php">
function hook_create_forum_account($vars)
{
$firstname = $vars['firstname'];
$lastname = $vars['lastname'];
$email = $vars['email'];

# Run code to create remote forum account here...
}

add_hook('ClientAdd', 1, 'hook_create_forum_account');
</syntaxhighlight >

==The Add Hook Function==

This is the key function for hooks, and is how you define to WHMCS at what point your custom hook function should be called.

*The first part defines the hook point. This must be one of the hook points WHMCS has implemented (listed in the pages below)
*The number defines the priority of the hook, so for example if you have more than 1 hook for the ClientAdd function, the order in which the hooks should run
*The third argument tells WHMCS which function to call from this hook point and so this is where you put the name of the custom hook file you create

A commented out example hook file is included in WHMCS which you can use as a template. You'll find that in the folder /includes/hooks/

==Module Hooks==

As of WHMCS V4.4, addon modules support hooks being defined that relate to a module within the module directory in /modules/addons/

And as of WHMCS V5.0, both product/server/provisioning modules and domain registrar modules also support hooks being defined within the relevant modules directories.

To define hooks as part of a module, simple create a file named "hooks.php" within the module folder, and include all module specific hook related code within that file.

''Note to Developers:'' Hook files in module folders are only called for active modules. And active modules that contain hooks are cached. So if you add a hooks file to a module retrospectively, once the module is already active, then before the system will detect and start running that module, you must edit and resave either the addon module configuration, product configuration or domain registrar configuration for the respective module for it to be detected.

==Hook Points==

We've divided the hooks up into categories to help make the list more managable. So simply choose an option from below to see the hooks which exist for that category.

{{Hook_Categories}}

There is also an [[Hooks:Alphabetical|alphabetical list]] of hooks available

{{Developer_Links}}

Working With Client Area Home Page Panels

2015-07-08T21:54:13Z

Kevin:

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==

[[Image:Desktop mode client panels.png|thumb|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.

<div style="clear: both"></div>

==Responsive Mode==

[[Image:Responsive mode client panels.png|thumb|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.

<div style="clear: both"></div>

=Differences With Navigation And Sidebar Menu Items=

[[Image:Client area panel item.png|thumb|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.

<div style="clear: both"></div>

=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.

{| 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 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’ <tt>add_hook()</tt> 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==

[[Image:Local temperatures home page panel.png|thumb|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 <tt>addChild()</tt> and <tt>moveToFront()</tt> methods. The <tt>WHMCS\User\Client</tt> class contains the information to query for 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 version 6. To add this panel to the client area home page we must:

# 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 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.
# 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 it's displayed 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 on page load and will run the hook function when the client visits the home page after logging in.

<div style="clear: both"></div>

<syntaxhighlight lang="php">
<?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}°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:Redeem offer home page panel.png|thumb|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 <tt>addChild()</tt> 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:

# 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.
# 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 precious 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.

<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>

Version 6 Template Migration Guide

2015-07-08T07:07:02Z

Kevin:

=Smarty Templating Changes=

WHMCS has gone through a number of backend changes in version 6. Included amongst them was the internal upgrade from Smarty 2 to Smarty 3.1. Most custom templates won't need any updates to be compatible with version 6, but those that used features only available in Smarty 2 will need to be migrated to ensure a smooth transition to the latest version.

<div class="docs-alert-info">The inverse of this change is also true. Custom templates made for WHMCS 6 that use Smarty 3 specific syntax are not compatible with previous versions of WHMCS.</div>

=={literal} Changes==

Smarty 3's engine changes the way whitespace is interpreted in templates, removing the need for {literal} tags around "{" and "}" characters in CSS and Javascript blocks.

For example, the following Javascript from a Smarty template:

<syntaxhighlight lang="smarty">
<script type="text/javascript">
function example()
{literal}{{/literal}
alert('example');
{literal}}{/literal}
</script>
</syntaxhighlight>

Converts to:

<syntaxhighlight lang="smarty">
<script type="text/javascript">
function example()
{
alert('example');
}
</script>
</syntaxhighlight>

=={php} Block Syntax==

<div class="docs-alert-info">An option was added to WHMCS 6 to enable use of the potentially dangerous {php} tag in custom templates. This option is disabled by default but can be enabled if required in '''Setup > General Settings > Security'''. We strongly encourage using hook functions over php code blocks inside of templates for backend interaction.</div>

Smarty 3's backwards compatibility layer defines the {php} tag as a block plugin instead of a method native to the Smarty object. Combined with Smarty's internal rewrite in version 3, some syntax available within a Smarty 2 {php} block will need small modification.

{| class="wikitable" |
|-
! Original syntax
! New syntax
! Notes
|-
| <tt>$this</tt>
| <tt>$template</tt>
| All Smarty 3 block plugins have a <tt>$template</tt> parameter containing the current Smarty instance.
|-
| style="white-space: nowrap" | <tt>$this->_tpl_vars</tt>
| <tt>$template->getVariable('variableName')</tt> or <tt>$template->getTemplateVars()</tt>
| Template variables are represented by <tt>Smarty_Variable</tt> objects in Smarty 3, which have a value property.
|-
|}

For example, the following {php} block:

<syntaxhighlight lang="php">
{php}

// Retrieve a single template variable.
$myValue = $this->_tpl_vars['myVariable'];

// Loop through all template variables.
foreach ($this->_tpl_vars as $key => $value) {
echo "{$key}: {$value}";
}

// Assign a new template variable.
$this->assign('myNewVariable', 'myNewValue');

{/php}
</syntaxhighlight>

Converts to:

<syntaxhighlight lang="php">
{php}

// Retrieve a single template variable.
$myValue = $template->getVariable('myVariable')->value;

// Loop through all template variables.
foreach ($template->getTemplateVars() as $key => $variable) {
echo "{$key}: {$variable->value}";
}

// The assign() method works as it did before, though it must now be
// called on the $template object instead of $this.
$template->assign('myNewVariable', 'myNewValue');

{/php}
</syntaxhighlight>

It is also importing to note that because of these changes, PHP code blocks that close in the middle of a condition, such as the below example, are now no longer possible and result in a fatal error.

<syntaxhighlight lang="php">
{php}
if ($foo) {
{/php}
<div>
Lots of HTML here...
</div>
{/php}
}
{/php}
</syntaxhighlight>

===Migrating From {php} Tags To Hooks===

It's a good practice to separate backend logic from display logic. In most cases a template's {php} block can be migrated to a hook file. Hooks are very useful for performing custom actions at specific points in WHMCS's page generation routines. See [[PHP Logic within Templates]] for more information.

For instance, one can reference existing template variables or define new template variables in a PHP file in the <tt>includes/hooks</tt> directory. Inspect and assign variables using the "ClientAreaPage" hook.

<syntaxhighlight lang="php">
add_hook('ClientAreaPage', 1, function($templateVariables)
{
// Look for an existing template variable.
foreach ($templateVariables as $name => $variable) {
doThings();
}

// Define new variables to send to the template.
return array(
'myCustomVariable' => 'myCustomValue',
);
});
</syntaxhighlight>

And then reference the newly assigned variable in the template:

<syntaxhighlight lang="smarty">
<p>My custom variable value is: {$myCustomVariable}.</p>
</syntaxhighlight>

=The $client Object=

All client area templates now have a <tt>$client</tt> variable that represents the currently logged in client. <tt>$client</tt> is either a <tt>WHMCS\Client\User</tt> object or ''null'' if no client is logged in. See [[Using Models]] for more information on how to work with model-based objects.

<syntaxhighlight lang="smarty">
{if $client === null}
<p>Nobody is logged in. :(</p>
{else}
<p>Hello, {$client->firstName} {$client->lastName}!</p>
{/if}
</syntaxhighlight>