Difference between revisions of "Working with Module Templates"
(Created page with "Modules that provide user facing output typically use templates to define and control that output. There are some exceptions, most often in the case of older modules, but all...") |
|||
| 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. |
==How Templates Work== | ==How Templates Work== | ||
| Line 5: | Line 5: | ||
Module template files can exist in either the root directory of the module, or in a subfolder named "templates". | Module template files can exist in either the root directory of the module, or in a subfolder named "templates". | ||
| − | + | ==Version Specific Templates== | |
| + | |||
| + | Modules can also provide templates that are designed to work with specific client area templates. It's easiest to explain this with an example. | ||
| + | |||
| + | Take WHMCS 6.0 for example, there are two themes we ship by default: five and six. The six theme implements the Bootstrap 3 framework, while the five theme implements Bootstrap 2. As there are differences between the two in the way styling and structures are applied, a template that works for one doesn't work so well for the other. And that's where Version Specific Templates come in. | ||
| + | |||
| + | What this allows is for you to define a template that is used by default, regardless of template, and then other templates which are used with specific templates, for example such as providing an older Bootstrap 2 compatible template for use with the five theme. We do this in a few of our included addons and modules, whereby the default is optimised for the Six theme with Bootstrap 3, while a five version is provided in addition for older based themes. | ||
If your custom theme is based on the five template, you would likely want to consider using the overrides system below to have your custom template define the version optimised for five is used. | If your custom theme is based on the five template, you would likely want to consider using the overrides system below to have your custom template define the version optimised for five is used. | ||
| Line 11: | Line 17: | ||
==Customising Templates== | ==Customising Templates== | ||
| − | Module templates can be customised using an overrides system that allows customisations to be | + | Module templates can be customised using an overrides system that allows customisations to be made within your active client area template theme folder. This has a number of advantages: |
| − | + | * Customisations remain unaffected through upgrades | |
| + | * All of your customisations are kept in a crentralised location | ||
| + | * Customisations of module templates are portable with themes | ||
| + | * Backing up customisations is easier | ||
| − | + | <div class="docs-alert-info">'''Recommended''' This functionality was introduced in WHMCS 6.0.</div> | |
To create an override template, simply make a copy of the original template file within the following folder structure inside your custom template: ''/templates/yourtemplatename/modules/moduletype/modulename/''. | To create an override template, simply make a copy of the original template file within the following folder structure inside your custom template: ''/templates/yourtemplatename/modules/moduletype/modulename/''. | ||
Revision as of 08:27, 25 June 2015
Modules that provide user facing output typically use templates to define and control that output.
How Templates Work
Module template files can exist in either the root directory of the module, or in a subfolder named "templates".
Version Specific Templates
Modules can also provide templates that are designed to work with specific client area templates. It's easiest to explain this with an example.
Take WHMCS 6.0 for example, there are two themes we ship by default: five and six. The six theme implements the Bootstrap 3 framework, while the five theme implements Bootstrap 2. As there are differences between the two in the way styling and structures are applied, a template that works for one doesn't work so well for the other. And that's where Version Specific Templates come in.
What this allows is for you to define a template that is used by default, regardless of template, and then other templates which are used with specific templates, for example such as providing an older Bootstrap 2 compatible template for use with the five theme. We do this in a few of our included addons and modules, whereby the default is optimised for the Six theme with Bootstrap 3, while a five version is provided in addition for older based themes.
If your custom theme is based on the five template, you would likely want to consider using the overrides system below to have your custom template define the version optimised for five is used.
Customising Templates
Module templates can be customised using an overrides system that allows customisations to be made within your active client area template theme folder. This has a number of advantages:
- Customisations remain unaffected through upgrades
- All of your customisations are kept in a crentralised location
- Customisations of module templates are portable with themes
- Backing up customisations is easier
To create an override template, simply 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", /modules/servers/cpanel/overview.tpl could be customised by creating the following template file: /templates/yourtemplatename/modules/servers/cpanel/overview.tpl
Another example, this time based upon the provisioning module "licensing", /modules/servers/licensing/templates/managelicense.tpl can be customised by creating the following template file /templates/yourtemplatename/modules/servers/licensing/managelicense.tpl
The same thing applies to addon modules too. For example the client area view template located in /modules/addons/project_management/templates/clientview.tpl' could be customised by creating the template file /templates/yourtemplatename/modules/project_management/templates/clientview.tpl.