Difference between revisions of "Modifying a Joomla! Template"
From Joomla! Documentation
m (→Editing the template: clean up categories with <noinclude> tags) |
m (added Category:Tutorials using HotCat) |
||
(24 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | Templates are just a | + | {{version|2.5,3.1}} |
− | You can edit these files or | + | Templates are just a group of XML, PHP, HTML and image files that are stored in the ''templates'' directory of your site. You can edit these files directly or use the Template Manager. |
+ | == Before You Begin == | ||
+ | Before you start hacking away at a default installed template, remember that any updates of the Joomla core files is likely to contain new copies of the default templates. Unless you take steps to protect your work, your modifications will be lost. | ||
− | + | There are options in the Template Manager to Duplicate and Copy an existing template. Note that you are only copying the style of the template and you are '''not''' protected from overwrites. There is simply another entry made in the ''_template_styles'' table of the database. The template files are '''not''' duplicated into another uniquely-named directory and they will be overwritten during an upgrade. | |
− | |||
− | === | + | For example, consider the case in which you Duplicate the Protostar template in the Template Manager and then modify the ''/templates/protostar/css/template.css'' file. A Joomla upgrade is likely to contain a full set of those Protostar template files. Your changes will be lost. |
− | Create a new template: | + | === Copy an Existing Template === |
− | *Create a new | + | Create a new template by copying an existing template: |
− | *Copy the contents of the original ''template'' directory to the my_template directory. | + | *Create a new ''/templates/my_template'' directory. |
− | *Go to the language/en-GB directory | + | *Copy the contents of the original ''template'' directory to the ''my_template'' directory. |
− | *Open the templateDetails.xml file in the my_template directory and change | + | *Go to the root ''/language/en-GB'' directory. |
− | + | **Copy ''/language/en-GB/en-GB.tpl_original_template.ini'' to ''en-GB.tpl_my_template.ini'' | |
− | + | **Copy ''/language/en-GB/en-GB.tpl_original_template.sys.ini'' to ''en-GB.tpl_my_template.sys.ini'' | |
− | + | *Go to the ''/language/en-GB'' directory in the template's directory, if it exists. | |
+ | **Copy ''/language/en-GB/en-GB.tpl_original_template.ini'' to ''en-GB.tpl_my_template.ini'' | ||
+ | **Copy ''/language/en-GB/en-GB.tpl_original_template.sys.ini'' to ''en-GB.tpl_my_template.sys.ini'' | ||
+ | *Open the ''templateDetails.xml'' file in the ''my_template'' directory and change '''all''' references, if they exist, for the original template directory to the new directory ''my_template''. | ||
+ | |||
+ | <syntaxhighlight lang="xml"><name>My_Template</name></syntaxhighlight> | ||
+ | |||
+ | <syntaxhighlight lang="xml"><language tag="en-GB">en-GB.tpl_my_template.ini</language> | ||
+ | <language tag="en-GB">en-GB.tpl_my_template.sys.ini</language></syntaxhighlight> | ||
+ | |||
+ | <syntaxhighlight lang="xml"> | ||
<param name="theme_header" type="folderlist" directory="templates/my_template/styles/header" default="" label="Header Themes" description="HEADER THEMES DESCRIPTION" /> | <param name="theme_header" type="folderlist" directory="templates/my_template/styles/header" default="" label="Header Themes" description="HEADER THEMES DESCRIPTION" /> | ||
<param name="theme_background" type="folderlist" directory="templates/my_theme/styles/background" default="" label="Background Themes" description="BACKGROUND THEMES DESCRIPTION" /> | <param name="theme_background" type="folderlist" directory="templates/my_theme/styles/background" default="" label="Background Themes" description="BACKGROUND THEMES DESCRIPTION" /> | ||
− | <param name="theme_elements" type="folderlist" directory="templates/my_theme/styles/elements" default="" label="Primary Elements" description="PRIMARY ELEMENTS DESCRIPTION" /></ | + | <param name="theme_elements" type="folderlist" directory="templates/my_theme/styles/elements" default="" label="Primary Elements" description="PRIMARY ELEMENTS DESCRIPTION" /></syntaxhighlight> |
+ | === Discover the New Template === | ||
+ | Now the new template must be introduced to your Joomla site through the discovery process. | ||
+ | |||
+ | *Go to {{rarr|Administrator,Extensions,Extension Manager,Discover}} | ||
+ | *Click the Discover icon. | ||
+ | *Select your new template. | ||
+ | *Click Install. | ||
+ | |||
+ | If successful, the new template will now be available in {{rarr|Administrator,Extensions,Template Manager}} | ||
+ | |||
+ | *Make the new template the default template. | ||
+ | *View the site to verify it. | ||
− | === | + | ==Using the Template Manager== |
− | + | === Editing the Template === | |
+ | {{:J{{CurrentSTSVer|minor}}:Editing a template with Template Manager}} | ||
+ | == Finding Errors == | ||
+ | You might have problems as a result of copying an existing template to a new template. Because of the way that Joomla handles file names, you might be tripped up by a capitalization error, for example. | ||
− | + | Joomla contains some useful debugging tools. To see what is happening while working on a site, there are three settings that you should change. | |
− | |||
− | |||
− | |||
− | ''' | + | # ''Administration > Site > Global Configuration > System > Debug Settings > Debug System > Yes'' (Default = ''No'') |
− | + | # ''Administration > Site > Global Configuration > System > Debug Settings > Debug Language > Yes'' (Default = ''No'') | |
− | + | # ''Administration > Site > Global Configuration > Server > Server Settings > Error Reporting > Maximum'' (Default = ''System Default'') | |
− | |||
− | |||
− | + | With the Debug Language set to ''Yes'', for instance, you will see the success or failure of language file loading on each page of the Administrator. Open the ''Joomla Debug Console > Language Files Loaded'' panel to view the report. | |
− | <noinclude> | + | <noinclude> |
− | [[Category: | + | [[Category:Template Development]] |
− | [[Category: | + | [[Category:Template Development FAQ]] |
− | [[Category: | + | [[Category:Template Reference]] |
− | + | [[Category:Tutorials]] | |
− | [[Category: | + | </noinclude> |
− |
Revision as of 20:12, 23 June 2013
Templates are just a group of XML, PHP, HTML and image files that are stored in the templates directory of your site. You can edit these files directly or use the Template Manager.
Before You Begin[edit]
Before you start hacking away at a default installed template, remember that any updates of the Joomla core files is likely to contain new copies of the default templates. Unless you take steps to protect your work, your modifications will be lost.
There are options in the Template Manager to Duplicate and Copy an existing template. Note that you are only copying the style of the template and you are not protected from overwrites. There is simply another entry made in the _template_styles table of the database. The template files are not duplicated into another uniquely-named directory and they will be overwritten during an upgrade.
For example, consider the case in which you Duplicate the Protostar template in the Template Manager and then modify the /templates/protostar/css/template.css file. A Joomla upgrade is likely to contain a full set of those Protostar template files. Your changes will be lost.
Copy an Existing Template[edit]
Create a new template by copying an existing template:
- Create a new /templates/my_template directory.
- Copy the contents of the original template directory to the my_template directory.
- Go to the root /language/en-GB directory.
- Copy /language/en-GB/en-GB.tpl_original_template.ini to en-GB.tpl_my_template.ini
- Copy /language/en-GB/en-GB.tpl_original_template.sys.ini to en-GB.tpl_my_template.sys.ini
- Go to the /language/en-GB directory in the template's directory, if it exists.
- Copy /language/en-GB/en-GB.tpl_original_template.ini to en-GB.tpl_my_template.ini
- Copy /language/en-GB/en-GB.tpl_original_template.sys.ini to en-GB.tpl_my_template.sys.ini
- Open the templateDetails.xml file in the my_template directory and change all references, if they exist, for the original template directory to the new directory my_template.
<name>My_Template</name>
<language tag="en-GB">en-GB.tpl_my_template.ini</language>
<language tag="en-GB">en-GB.tpl_my_template.sys.ini</language>
<param name="theme_header" type="folderlist" directory="templates/my_template/styles/header" default="" label="Header Themes" description="HEADER THEMES DESCRIPTION" />
<param name="theme_background" type="folderlist" directory="templates/my_theme/styles/background" default="" label="Background Themes" description="BACKGROUND THEMES DESCRIPTION" />
<param name="theme_elements" type="folderlist" directory="templates/my_theme/styles/elements" default="" label="Primary Elements" description="PRIMARY ELEMENTS DESCRIPTION" />
Discover the New Template[edit]
Now the new template must be introduced to your Joomla site through the discovery process.
- Go to Administrator → Extensions → Extension Manager → Discover
- Click the Discover icon.
- Select your new template.
- Click Install.
If successful, the new template will now be available in Administrator → Extensions → Template Manager
- Make the new template the default template.
- View the site to verify it.
Using the Template Manager[edit]
Editing the Template[edit]
J3.10:Editing a template with Template Manager
Finding Errors[edit]
You might have problems as a result of copying an existing template to a new template. Because of the way that Joomla handles file names, you might be tripped up by a capitalization error, for example.
Joomla contains some useful debugging tools. To see what is happening while working on a site, there are three settings that you should change.
- Administration > Site > Global Configuration > System > Debug Settings > Debug System > Yes (Default = No)
- Administration > Site > Global Configuration > System > Debug Settings > Debug Language > Yes (Default = No)
- Administration > Site > Global Configuration > Server > Server Settings > Error Reporting > Maximum (Default = System Default)
With the Debug Language set to Yes, for instance, you will see the success or failure of language file loading on each page of the Administrator. Open the Joomla Debug Console > Language Files Loaded panel to view the report.