WHMCS Theme Structure Explained: Complete Developer Guide

Understanding WHMCS theme structure is essential for customization and development. This guide covers the complete architecture of WHMCS themes, from directory layout to template inheritance, helping you build and modify themes effectively.

WHMCS Theme Types

WHMCS uses different theme types for different areas:

1. Client Area Themes

Control the customer-facing portal where clients manage their accounts, services, and support tickets.

• Location: templates/
• Default: templates/twenty-one/
• Previous default: templates/six/

2. Order Form Templates

Control the shopping and checkout experience for purchasing products and services.

• Location: templates/orderforms/
• Options: standard_cart, ajaxcart, modern, etc.

3. Admin Area Themes

Control the staff/admin interface. Limited customization is supported.

• Location: admin/templates/
• Generally not customized

4. Email Templates

Stored in database, managed through admin panel. Uses Smarty syntax for dynamic content.

Client Area Theme Structure

Main Directory Layout

A typical client area theme contains:

Key Template Files

Theme.yaml Configuration

Structure

The theme.yaml file defines theme metadata and settings:

Key Properties

• name: Display name of theme
• author: Theme creator
• version: Theme version number
• parent: Parent theme for inheritance
• config: Customizable settings

Theme Inheritance

Child themes can inherit from parent themes:

• Only override files you want to change
• Inherit all other templates from parent
• Reduces maintenance when parent updates

Smarty Template Engine

What is Smarty?

WHMCS uses Smarty, a PHP template engine that separates presentation from logic. Templates use .tpl extension.

Basic Smarty Syntax

• Variables: Wrapped in curly braces
• Modifiers: Transform variable output
• Conditionals: if/else logic
• Loops: foreach for arrays
• Includes: Include other templates

Common Smarty Modifiers

• escape: HTML entity encoding
• truncate: Shorten text
• date_format: Format dates
• upper/lower: Case transformation
• default: Default value if empty

Available Template Variables

Global Variables

Available in all templates:

• companyname: Company name from settings
• systemurl: WHMCS system URL
• template: Current template name
• loggedin: User login status
• clientsdetails: Client information
• languages: Available languages

Page-Specific Variables

Each page provides relevant data:

• Products page: services array
• Domains page: domains array
• Invoice page: invoice details
• Support page: tickets array

Finding Available Variables

• Check WHMCS developer documentation
• Look at existing template usage
• Enable Smarty debugging (development only)

Order Form Structure

Order Form Directory

Each order form template is in its own folder:

• templates/orderforms/standard_cart/
• templates/orderforms/ajaxcart/
• templates/orderforms/modern/

Key Order Form Files

Creating a Custom Theme

Method 1: Child Theme (Recommended)

1. Create new folder in templates/
2. Create theme.yaml with parent specified
3. Copy only files you want to modify
4. Make your changes
5. Activate in Settings

Method 2: Full Copy

1. Copy entire parent theme folder
2. Rename to your theme name
3. Update theme.yaml
4. Make all desired changes
5. Note: More maintenance when WHMCS updates

Method 3: Hooks for Minor Changes

• Use ClientAreaHeadOutput for CSS/JS
• Use ClientAreaFooterOutput for scripts
• Survives theme updates
• Good for tracking codes, minor styling

Customization Best Practices

Update-Safe Customization

• Use child themes when possible
• Put CSS in custom.css, not styles.css
• Use hooks for injecting code
• Document all modifications
• Version control your changes

CSS Customization

• Use custom.css for overrides
• Avoid modifying core stylesheet
• Use specific selectors to avoid conflicts
• Consider CSS variables if supported

JavaScript Additions

• Add via ClientAreaFooterOutput hook
• Use custom.js file in theme
• Namespace your code
• Check for jQuery conflicts

Template Debugging

Enable Debug Mode

• Set display_errors in configuration.php
• Check WHMCS activity log
• Use browser developer tools

Common Issues

• Blank page: Syntax error in template
• Missing variable: Check variable name spelling
• Styles not loading: Clear template cache
• Changes not showing: Clear browser cache

Clearing Template Cache

• Utilities → System → System Cleanup
• Check "Template Cache"
• Click "Empty Selected Items"
• Required after template changes

Asset Management

Images

• Store in theme's /images/ folder
• Reference relative to theme root
• Consider CDN for performance
• Optimize image sizes

Fonts

• Store locally or use Google Fonts
• Consider font subsetting
• Use font-display: swap

Third-Party Libraries

• Check for conflicts with WHMCS included libraries
• jQuery is already included
• Bootstrap may conflict with existing styles

Mobile Responsiveness

Testing Requirements

• Test on actual mobile devices
• Check all breakpoints
• Verify touch targets are adequate
• Test checkout flow on mobile

Common Mobile Issues

• Tables not scrolling horizontally
• Forms too wide for screen
• Buttons too small to tap
• Navigation not mobile-friendly

Theme Checklist

Conclusion

Understanding WHMCS theme structure empowers you to create customized client experiences that match your brand. Use child themes and hooks for update-safe modifications, and always test thoroughly across devices and browsers before deploying changes.