Difference between revisions of "Customising the Six Theme"

Revision as of 07:44, 16 April 2015

Six is the name of the default client area template theme that ships with WHMCS 6.0 and later.

Before You Begin

Before you start to make customisations, we recommend you create a copy of the six template to work on. This ensures your customisations aren't lost when you upgrade.

Create a new folder with the desired name for your template. The directory name must be all lowercase a-z 0-9 characters.
Upload a copy of the files from the six template folder into your new folder

While developing, you can preview how your new template looks without changing what your customers see by using the URL template parameter setting as follows: http://www.yourdomain.com/whmcs/?systpl=yourtemplatename

More information on this and other url option parameters can be found in the Linking to WHMCS documentation.

Third Party Assets

The six theme uses the latest available versions of the following libraries:

Bootstrap - http://www.getbootstrap.com/
Font Awesome - http://fortawesome.github.io/Font-Awesome/
jQuery - http://www.jquery.com/

Therefore you can use any of the functionality offered by these libraries within the template files.

Bootstrap

Bootstrap is our HTML and CSS framework of choice and is used throughout the admin and client areas.

Extensive documentation is available on working with bootstrap and all that bootstrap has to offer in the way of CSS styles and components on the official bootstrap website @ http://www.getbootstrap.com/

The bootstrap files are located within the /assets/ directory and are shared by the admin and client area. We strongly recommend you do not make any changes to the bootstrap files directly.

Customising the Design/Layout

Header & Footer

The header and footer template files are common to every page displayed as a wrapper around the primary body content. Typically these are the most popular two template files our users edit. Customising these to match your website allows you to give end users a seamless experience when browsing your website.

Key Points

We strongly recommend you maintain all of the template includes and output variables present in the default template files in your custom header/footer as this will help ensure compatibility with addons and extensions you later install
Navigation bar and Sidebar content is defined within WHMCS and passed to the templates for output. This allows modules and addons to interact with and manipulate these areas of the client area dynamically. The output styling of these is controlled by include files which are explained in more detail below.
The footer template file includes a number of lines of javascript code immediately prior to the closing </body> tag which are essential to the correct operation of the client area. Please take care not to remove these lines.

Include Files

Include templates are templates that are shared and used by multiple pages. They are located within the /includes/ sub-directory.

Common to All Pages

head.tpl - Defines the CSS & Javascript files included within the <head> section of a page
navbar.tpl - Controls the output of the primary navigation bar menu items
sidebar.tpl - Controls the output of the sidebar menu items

Used as Required

captcha.tpl - Used to output the captcha verification image wherever used
pwstrength.tpl - Used to output the password strength meter and tooltip wherever used
tablelist.tpl - Controls the output of all filterable data list tables throughout the client area

Editing any of these template files will affect everywhere that the respective elements are used. One place to edit, and one place to maintain during upgrades, will help make applying and preserving your customisations easier.

Helpers

For common elements that are used accross multiple pages, we have created helpers via the use of include files that make it both easier to use those elements and to customise them in a consistent way throughout the entire theme.

The helpers include:

Page Header

To include a header on a page, use the following syntax:

{include file="$template/includes/pageheader.tpl" title=$LANG.globalsystemname desc=$LANG.subheadinggoeshere showbreadcrumb=true}

Show breadcrumb can be set to false to hide the default breadcrumb output for a given page.

Alerts

To include an alert in a page, use the following syntax:

{include file="$template/includes/alert.tpl" type="info" textcenter=true hide=false additionalClasses="my-custom-class" idname="my-alert" title="Optional title goes here" msg="Message to display goes here"}

Type can be any one of the bootstrap standard types: info, warning, success & danger

The title and message parameters can use language variables, for example $LANG.globalsystemname

Setting hide to true allows you to have an alert that is hidden by default. This is useful if you want to have your alert be revealed by a javascript action.

Panels

To include a panel on a page, use the following syntax:

{include file="$template/includes/panel.tpl" type="warning" headerTitle="Optional title goes here" bodyContent="Body content to display goes here" footerContent="Optional footer content goes here"}

Type can be any one of the bootstrap standard types: info, warning, success & danger

All output content, title, body and footer can use language variables, for example $LANG.globalsystemname

Breadcrumb Navigation

This will show the full path to the current page. It has no input parameters:

{include file="$template/includes/breadcrumb.tpl"}

Applying Custom CSS Styling

If you want to make changes to any of the CSS that is applied by default, we recommend making those customisations inside of the /css/custom.css file.

This file is included after styles.css allowing you to override any of the CSS defined within it, and will not be affected by future updates to the WHMCS software and therefore will help ensure that any customisations you have made do not get overwritten or lost while still allowing you to keep the styles.css file up-to-date and current.

Do not edit styles.css
We strongly discourage making any changes to the /css/styles.css template file directly.

Making Your Custom Template Live

Once you're happy with your new template and are ready to make it live, just follow these 3 simple steps:

Login to the Admin Area
Navigate to Setup > General Settings
Under the Template setting on the General tab, select the name of the template you created above
Hit Save Changes and now visitors to your site will see that template

Documentation