Difference between revisions of "Working with Module Templates"
(→Customising Templates) |
|||
| Line 1: | Line 1: | ||
| − | Modules that provide user facing output typically use templates to define and control that output. | + | [[Modules]] that provide user facing output typically use templates to define and control that output. |
| − | Module template files can exist in either the root directory of the module, or in a subfolder | + | Module template files can exist in either the root directory of the module, or in a <tt>templates</tt> subfolder. |
==Customising Templates== | ==Customising Templates== | ||
| − | + | You can customize module templates using an overrides system that allows customisations within your active client area template theme folder. We recommend this for several reasons: | |
| − | * | + | * Customizations remain unaffected through upgrades. |
| − | * All of your customisations | + | * All of your customisations remain in a centralized location. |
| − | * | + | * Customizations of module templates are portable with themes. |
| − | * Backing up | + | * Backing up customizations is easier. |
<div class="docs-alert-warning">This functionality was introduced in WHMCS 6.0.</div> | <div class="docs-alert-warning">This functionality was introduced in WHMCS 6.0.</div> | ||
| − | To create an override template, | + | To create an override template, make a copy of the original template file within the following folder structure inside your custom template: <tt>/templates/yourtemplatename/modules/moduletype/modulename/</tt> |
| − | For example, in the case of the provisioning module | + | For example, in the case of the provisioning module <tt>cpanel</tt>, you could customize <tt>/modules/servers/cpanel/overview.tpl</tt> by creating the following template file: <tt>/templates/yourtemplatename/modules/servers/cpanel/overview.tpl</tt> |
| − | Another example, this time based upon the provisioning module | + | Another example, this time based upon the provisioning module <tt>licensin</tt>, you can customize <tt>/modules/servers/licensing/templates/managelicense.tpl</tt> by creating the following template file: <tt>/templates/yourtemplatename/modules/servers/licensing/managelicense.tpl</tt> |
| − | + | This also applies to addon modules. For example, you can customize the client area view template in <tt>/modules/addons/project_management/templates/clientview.tpl</tt> by creating this template file: <tt>/templates/yourtemplatename/modules/addons/project_management/clientview.tpl</tt> | |
==Version Specific Templates== | ==Version Specific Templates== | ||
| − | Modules can also provide templates that | + | Modules can also provide templates that work with specific client area templates. |
| − | + | In WHMCS 6.0, for example, there are two themes included by default: five and six. The six theme implements the Bootstrap 3 framework, while the five theme implements Bootstrap 2. Because of differences in how they apply styling and structures, a template that works for may not work for the other. Because of this, WHMCS supports Version Specific Templates. | |
| − | + | This allows you to define a default template with additional templates to use in conjunction with specific system templates. For example, this could provide an older Bootstrap 2-compatible template for use with the five theme. We do this in a few of our included addons and modules, in which the default is optimized for the six theme with Bootstrap 3, while a five version is provided in addition for older based themes. | |
| − | <div class="docs-alert- | + | <div class="docs-alert-warning"> |
| + | <span class="title">Note</span><br /> | ||
| + | If your custom theme is based on the five template, you might want to consider using the overrides system to have your custom template define the version optimised for five. | ||
| + | </div> | ||
Revision as of 21:07, 1 June 2020
Modules that provide user facing output typically use templates to define and control that output.
Module template files can exist in either the root directory of the module, or in a templates subfolder.
Customising Templates
You can customize module templates using an overrides system that allows customisations within your active client area template theme folder. We recommend this for several reasons:
- Customizations remain unaffected through upgrades.
- All of your customisations remain in a centralized location.
- Customizations of module templates are portable with themes.
- Backing up customizations is easier.
To create an override template, make a copy of the original template file within the following folder structure inside your custom template: /templates/yourtemplatename/modules/moduletype/modulename/
For example, in the case of the provisioning module cpanel, you could customize /modules/servers/cpanel/overview.tpl by creating the following template file: /templates/yourtemplatename/modules/servers/cpanel/overview.tpl
Another example, this time based upon the provisioning module licensin, you can customize /modules/servers/licensing/templates/managelicense.tpl by creating the following template file: /templates/yourtemplatename/modules/servers/licensing/managelicense.tpl
This also applies to addon modules. For example, you can customize the client area view template in /modules/addons/project_management/templates/clientview.tpl by creating this template file: /templates/yourtemplatename/modules/addons/project_management/clientview.tpl
Version Specific Templates
Modules can also provide templates that work with specific client area templates.
In WHMCS 6.0, for example, there are two themes included by default: five and six. The six theme implements the Bootstrap 3 framework, while the five theme implements Bootstrap 2. Because of differences in how they apply styling and structures, a template that works for may not work for the other. Because of this, WHMCS supports Version Specific Templates.
This allows you to define a default template with additional templates to use in conjunction with specific system templates. For example, this could provide an older Bootstrap 2-compatible template for use with the five theme. We do this in a few of our included addons and modules, in which the default is optimized for the six theme with Bootstrap 3, while a five version is provided in addition for older based themes.
Note
If your custom theme is based on the five template, you might want to consider using the overrides system to have your custom template define the version optimised for five.