Difference between revisions of "Customising the Six Theme"

Revision as of 02:55, 23 September 2015

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

Before You Begin

Using Source Control

We make the Six theme available as a read-only repository on Github that enables you to build your template in a way that can be version controlled with Git, along with the ability to pull in and auto-merge future changes.

To find out more, including usage instructions, please visit https://github.com/WHMCS/templates-six/blob/master/README.md

Without Source Control

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

Creating a custom directory in this way ensures your customisations aren't lost when upgrading.

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.

Navigation Bar

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.

Responsive mode is activated when WHMCS’ client area is viewed on a smaller screen device such as a phone or tablet. At that point, WHMCS will collapse the navbar into a fold out menu.

The navigation bar elements are controlled in a programmatic way allowing modules and hooks to dynamically interact with the navigation menu elements.

The look and feel of the navigation bar can be customised via the header.tpl and navbar.tpl (located in /includes/) template files.

To change the items within a menu, please refer to the Editing Client Area Menus documentation.

Sidebars

There are two sidebars in WHMCS’ client area. The primary sidebar contains sidebar elements that are displayed above the body content when in responsive mode. The secondary sidebar contains sidebar elements that are displayed below the body content when in responsive mode. In desktop mode, there will be no noticeable difference between primary and secondary sidebar items.

The sidebar elements and panels are controlled in a programmatic way allowing modules and hooks to dynamically interact with the sidebar items.

The look and feel of the sidebar can be customised via the header.tpl and sidebar.tpl (located in /includes/) template files.

To change the items within a sidebar, please refer to the Editing Client Area Menus documentation.

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

We're on Github

The Six template theme is made available via Github to provide version-by-version changes of the “Six” template as published in WHMCS. Sharing these changes through GitHub as a read-only repository enables you to quickly inspect and import these changes for your custom theme.

https://github.com/WHMCS/templates-six

Version Changes

To view the changes to the Six theme in a particular version, simply click on the Version number at https://github.com/WHMCS/templates-six/commits/master

Documentation