Difference between revisions of "Working with Module 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 named "templates". | Module template files can exist in either the root directory of the module, or in a subfolder named "templates". | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==Customising Templates== | ==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. | + | Module templates can be customised using an overrides system that allows customisations to be made within your active client area template theme folder. We recommend this for a number of reasons: |
* Customisations remain unaffected through upgrades | * Customisations remain unaffected through upgrades | ||
| − | * All of your customisations are kept in a | + | * All of your customisations are kept in a centralised location |
* Customisations of module templates are portable with themes | * Customisations of module templates are portable with themes | ||
* Backing up customisations is easier | * Backing up customisations is easier | ||
| Line 33: | Line 21: | ||
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''. | 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''. | ||
| + | |||
| + | ==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. | ||
Revision as of 08:29, 25 June 2015
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 named "templates".
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. We recommend this for a number of reasons:
- Customisations remain unaffected through upgrades
- All of your customisations are kept in a centralised 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.
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.