CloudTail for WHMCS — User Documentation

What you get

CloudTail ships as two matched packages that share one design system — purple brand, Clash Display headlines, and Plus Jakarta Sans UI type.

Package	Folder	Purpose
Client area theme	`templates/cloudtail`	Dashboard, services, billing, support, account, auth, store
Order form	`templates/orderforms/cloudtail_cart`	Products, domains, configure, checkout, renewals
Hook loader	`install/cloudtail.php`	Copy into `includes/hooks/` for dashboard & list data

WHMCS contracts preserved. Smarty variables, form field names, AJAX endpoints, CSRF tokens, and Menu API hooks stay intact so third-party modules continue to work.

Features

Everything a hosting provider needs for a polished client portal and checkout.

App / Guest / Bare layouts

Logged-in sidebar shell, marketing guest chrome, and full-bleed auth screens — chosen automatically per page.

Rich dashboard

KPI tiles, recent services, invoices, domains, tickets, affiliates, and announcements powered by theme hooks.

Smart sidebar

Collapsible groups, status badges, quick actions, mobile drawer, and a More group for third-party nav items.

CloudTail Cart

Full order flow with live totals, domain search, configurable options, and gateway-safe checkout JS.

Auth experience

Login, register, password reset, 2FA, invite accept, and email verify with CloudTail branding.

Module friendly

Contextual right sidebar for Menu API actions; .wcompat protects injected HTML from Tailwind reset.

MarketConnect ready

Styled store landings and promo surfaces for SSL, email, SEO, and other MarketConnect products.

Responsive UI

Mobile drawer navigation, single-line top bar titles, and touch-friendly checkout on small screens.

Safe customization

custom.css overrides, logo via WHMCS assets, optional Tailwind rebuild pipeline.

Requirements

Tested and declared against WHMCS 9.0.6 library versions.

Server & platform

WHMCS 9.0.6 (recommended / tested)
PHP with WHMCS-supported extensions
Write access only needed if editing files on the server

Declared libraries

Bootstrap 4.5.3
jQuery 1.12.4
Font Awesome 5.10.1
Node.js 18+ only if rebuilding CSS

You do not need to install Bootstrap, jQuery, or Font Awesome separately — CloudTail bundles the versions WHMCS expects.

Installation

Copy files, install the Freemius license addon, activate your key, then turn on the theme.

License required: CloudTail will not run as the active theme/cart until the cloudtail_license addon reports a valid Freemius license. Unlicensed installs fall back to twenty-one and standard_cart.

Copy theme folders into WHMCS

Upload both packages into your WHMCS root (the directory that contains configuration.php).

templates/cloudtail
  →  <whmcs-root>/templates/cloudtail

templates/orderforms/cloudtail_cart
  →  <whmcs-root>/templates/orderforms/cloudtail_cart

Install the CloudTail License addon (required)

Copy the Freemius license module so WHMCS can activate your key.

templates/cloudtail/install/modules/addons/cloudtail_license
  →  <whmcs-root>/modules/addons/cloudtail_license

Then: Configuration → System Settings → Addon Modules → activate CloudTail License → open the module → paste your Freemius license key → Activate license.

Get the key from your Freemius invoice or customer portal.

Install the hook loader (required)

WHMCS only auto-loads PHP from includes/hooks/. Copy the stub so dashboard and list pages receive data (only after a valid license).

templates/cloudtail/install/cloudtail.php
  →  <whmcs-root>/includes/hooks/cloudtail.php

Without this hook: the dashboard still loads, but recent services / invoices / domains / tickets show empty states. Services & domains lists miss category tabs.

Activate theme & cart in WHMCS Admin

Log in to Admin → Configuration → System Settings → General Settings.

General tab → System Theme → CloudTail
Ordering tab → Order Form Template → CloudTail Cart
Save changes and confirm the compatibility check passes

Post-install checklist

Verify these after activation before going live.

CloudTail License addon shows status valid
Client area loads with the purple sidebar and CloudTail branding
Dashboard shows stat cards and populated tables (hook installed)
Login / register use the full-bleed auth layout
Order form (cart.php) matches the client area style
Complete a test order end to end (product + domain or hosting)
Third-party modules you rely on still render (product details sidebars, addons)
Mobile: hamburger opens drawer; Online badge and close button do not overlap
Language / currency modal opens when enabled

Using the client area

Layouts switch automatically — no admin setting required.

Layout modes

Mode	Used on	Chrome
App	Logged-in client area	296px sidebar + sticky top bar + main content
Guest	Store, KB, cart (logged out)	Marketing header & footer
Bare	Login, register, password reset, OAuth, errors	Full-bleed centered panel

Sidebar

Logo (WHMCS $assetLogoPath / company name)
Network status pill (Online / issues)
Client profile card and credit / add-funds CTA
Quick actions: order, knowledgebase, ticket, affiliates
Collapsible groups: Main, Billing, Support, Account
Unknown third-party menu items appear under More
Mobile: slide-in drawer with close control beside Online

Top bar

Mobile menu toggle and single-line page title
Knowledgebase search (desktop)
Resources dropdown (KB, announcements, downloads, network status, contact, Store)
Emails, cart badge, notifications, account menu
Language / locale switcher when enabled

Contextual right column

On product details, tickets, and domain management, WHMCS Menu API actions render as styled cards in a right column (wide viewports ≥1280px).

Using CloudTail Cart

Full checkout flow with standard_cart JavaScript contracts preserved.

Flow

Product group / product selection
Configurable options (live recalculation)
Domain register / transfer / existing
Addons & promotions
Review & checkout
Complete / confirmation

Preserved JS APIs

recalctotals()
updateConfigurableOptions()
removeItem()
selectDomainPricing()
validateCheckoutCreditCardInput()

Do not load a second copy of order-form scripts.min.js. CloudTail Cart relies on the theme’s single jQuery / Bootstrap bundle.

Customization

Prefer non-destructive overrides so theme updates stay easy.

Recommended: custom.css

Create templates/cloudtail/css/custom.css (and optionally cloudtail_cart/css/custom.css). Loaded automatically when present — ideal for brand colours, logo sizing, and module fixes.

Logo

Set your logo in WHMCS Admin → Setup → General Settings → Logo. CloudTail uses $assetLogoPath in the sidebar and guest header. Brand fallbacks live at images/cloudtail-logo.png.

Brand colours

Primary

#632AFF

Accent

#8E64FF

Page bg

#F6F7FB

Success

#00B386

Warning

#FF7A00

Danger

#FF005E

Info

#20C5E9

Ink

#100A22

Rebuild CSS (advanced)

cd templates/cloudtail/build
npm install
npm run build     # → ../css/cloudtail.css
npm run watch     # development

What to avoid

Do not rename form name/id attributes. Do not concatenate Tailwind classes in Smarty (text-{$color}). Do not load a second jQuery.

PHP hooks

Optional data enrichment loaded by the hook stub.

File	Purpose
`hooks/dashboard.php`	Recent services, invoices, domains, tickets for the home dashboard
`hooks/services.php`	Category tabs & colour metadata for services / domains lists
`hooks/auth.php`	Auth page sidebar cleanup on bare layouts
`hooks/guest-chrome.php`	Guest mega-menu product groups when logged out

Re-copy includes/hooks/cloudtail.php after any WHMCS reinstall that wipes the hooks folder.

File reference

Know where to look when customizing or supporting clients.

templates/cloudtail/ ├── theme.yaml # metadata + library versions ├── css/ │ ├── cloudtail.css # compiled (don’t hand-edit) │ ├── whmcs-compat.css # Bootstrap / WHMCS re-skin │ └── custom.css # your overrides ├── includes/ │ ├── sidebar-main.tpl # primary nav │ ├── topbar.tpl # sticky header │ ├── layout-context.tpl # bare / guest / app │ └── ui/ # badge, field, yes-no-switch… ├── hooks/ # dashboard, services, auth… ├── install/ │ ├── cloudtail.php # → includes/hooks/ │ └── modules/addons/cloudtail_license/ # → modules/addons/ ├── build/ # Tailwind toolchain ├── DOCUMENTATION.md └── README.md modules/addons/cloudtail_license/ # Freemius license unlock ├── cloudtail_license.php ├── hooks.php ├── helpers.php └── lib/ templates/orderforms/cloudtail_cart/ ├── theme.yaml ├── common.tpl ├── js/cart.js └── *.tpl # order flow

Troubleshooting

Common issues and quick fixes.

Client area falls back to the default theme

Cause: Missing or invalid Freemius license.
Fix: Install modules/addons/cloudtail_license, activate it under Addon Modules, paste your Freemius key, and click Activate. Status must show valid.

Dashboard tables are empty

Cause: Hook loader missing, or license not valid (hooks only load when licensed).
Fix: Activate the license first, then copy templates/cloudtail/install/cloudtail.php to includes/hooks/cloudtail.php.

Theme compatibility warning in Admin

Confirm WHMCS 9.0.6 and that theme.yaml still provides Bootstrap 4.5.3, jQuery 1.12.4, and Font Awesome 5.10.1.

Order form unstyled or JS errors

Set Order Form Template to CloudTail Cart. Verify cart.js and style.css exist. Clear browser cache and WHMCS template cache (Utilities → System → Clear Cache).

Module sidebar buttons missing

Actions live in the right contextual column — use a wide viewport (≥1280px). If Nexus shows them and CloudTail does not, report a theme regression.

Module HTML looks broken

Injected content should sit inside .wcompat. Add scoped fixes in custom.css if a module renders outside those wrappers.

New Tailwind classes missing after edits

Rebuild CSS from templates/cloudtail/build. Add runtime-toggled classes to safelist.txt.

Generate Password shows a dark overlay only

Ensure you are on the latest CloudTail CSS build — FlyonUI modal utilities must be overridden so Bootstrap .modal.show sits above the backdrop.

Upgrading WHMCS

CloudTail is standalone — it does not auto-inherit Nexus changes.

Back up templates/cloudtail, cloudtail_cart, and includes/hooks/cloudtail.php.
Install the new WHMCS version.
Diff CloudTail templates against templates/nexus and orderforms/standard_cart.
Re-apply visuals while keeping new WHMCS fields / variables.
Re-copy the hook stub if hooks were wiped.
Preserve your custom.css files.

Quality assurance

Run these before publishing an update or closing a support ticket.

cd templates/cloudtail/build
php check-templates.php   # Smarty compile check (theme + cart)
php check-langkeys.php    # verify {lang key=} against english.php

Manual test matrix

Login, register, password reset, two-factor challenge
Dashboard — stats and tables populated
Services, domains, invoices, tickets (list + detail)
Account details, contacts, security, payment methods
Order form — new + existing client through checkout
Mobile drawer, tables, and checkout
At least one third-party provisioning module

Publishing on WHMCS Marketplace

Tips when listing CloudTail on marketplace.whmcs.com.

Package contents

templates/cloudtail/ (full theme)
templates/orderforms/cloudtail_cart/
Hook stub under install/
Freemius license addon under install/modules/addons/cloudtail_license/
This documentation + README / UPGRADING
Screenshot set (desktop dashboard, mobile, cart, auth)

Listing checklist

Category: Templates & Themes
Compatible version: WHMCS 9.0.6+
Mention both System Theme + Order Form activation
Call out the required Freemius license addon + hook copy steps
Provide support contact & changelog
Own-site checkout: Freemius pricing page

Support

CloudTail preserves WHMCS core behaviour by design.

Check Troubleshooting above.
Run the QA scripts in build/.
Compare with the default Nexus theme — if it works in Nexus but not CloudTail, it is likely a template regression.
For module-specific problems, test with Nexus first to isolate theme vs module.