Created page with "WHMCS version 6 introduces a programmatic way to interact with the client area navigation and sidebars through hooks and modules. =Menu structure= The client area's navigati..."
New page
WHMCS version 6 introduces a programmatic way to interact with the client area navigation and sidebars through hooks and modules.
=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" | 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', [
'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', [
'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', [
'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', [
'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.
$primarySidebar->getFirstChild()->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', [
'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', [
'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', [
'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',
[
'icon' => 'fa-smile-o',
'order' => 1,
]
);
$supportHours->addChild(
'<strong>Closed</strong> Weekends',
[
'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>