Actions

J3.x

Difference between revisions of "Modifying a Joomla! Template"

From Joomla! Documentation

m (Editing the template: clean up categories with <noinclude> tags)
 
(53 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Templates are just a series of xml, php, html and image files that are stored in the templates directory of your site.
+
<noinclude><languages /></noinclude>
You can edit these files or you can use the editing interface available in the [[Template Manager]].
+
<translate><!--T:1-->
 +
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.</translate>
 +
<translate>== Before You Begin == <!--T:2--></translate>
 +
<translate><!--T:3-->
 +
Before you start hacking away at a default installed template or any other template you may have installed, remember that any updates of the Joomla core files may contain new copies of the default Joomla templates. Similarly, editing an installed template means you may have to re-install it to reset it to the original state at installation.</translate>
  
== Before you begin ==
+
<translate><!--T:4-->
Before you start hacking away at the a default installed template you may want to do ONE of the following. Doing one of these options will save you from worrying about any future updates to the Joomla source code that might overwrite your existing edits.
+
Unless you take steps to protect your work, modifications could be lost when upgrading Joomla. Likewise, you may want to preserve an installed template in case you have any problems with modifications to it.</translate>
  
=== Option One ===
+
<translate><!--T:5-->
Create a new template:
+
There are options in the [[S:MyLanguage/J{{ns}}:To_access_the_Template_Manager|Template Manager]] to Duplicate and Copy an existing template style or the '''actual template and template files'''. This page refers to the methods available to make a full copy of your template. This includes the style and all the template files of a template.</translate>
*Create a new directory templates/my_template
+
*Copy the contents of the original ''template'' directory to the my_template directory.
+
*Go to the language/en-GB directory and copy language/en-GB/en-GB.tpl_''template''.ini to en-GB.tpl_my_template.ini
+
*Open the templateDetails.xml file in the my_template directory and change ALL references for the original template directory to the new directory my_template.
+
*:<source lang="xml" line start="3"><name>My_Template</name></source>
+
*:<source lang="xml" line start="326"><language tag="en-GB">en-GB.tpl_my_template.ini</language></source>
+
*:<source lang="xml" line start="388">
+
<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" /></source>
+
  
=== Option Two ===
+
<translate><!--T:6-->
Make a backup/copy of the templates/template folder before and after your changes and make a note of what you have changed.
+
{{tip|Template Style and Template copying are not the same. You can make a copy of the template style but you are '''not''' protected from overwriting the actual template files. Style copying simply adds another entry made in the <code>''_template_styles''</code> table of the database. This is useful is you want to check a web site design with different fonts, colors, widths or logos if these template style parameters exist. The template files are '''not''' duplicated into another uniquely-named directory and they will be overwritten during an upgrade.}}</translate>
  
 +
<translate>==Copy the Template== <!--T:7--></translate>
 +
<translate><!--T:8-->
 +
To preserve your changes you need to Copy the template with all its files and styles. This procedure makes references to creating a full copy (an exact duplicate) of the template including all the files. In order to make a copy, you must be on the  '''Customise Template''' view.</translate>
 +
{{:J3.2:Access_Template_Manager_Customisation/<translate><!--T:9-->
 +
en</translate>}}
  
== Editing the template ==
+
<translate>== Copy an Existing Template == <!--T:10--></translate>
In the [[Back-end]], select Site>>[[Extension]]s>>Templates.
+
<translate>===The Easy Way=== <!--T:11--></translate>
Select the template you wish to modify.
+
<translate><!--T:12-->
Click the edit icon.
+
Create a new template by copying an existing template:
 +
*Click on Copy Template in Toolbar in [[S:MyLanguage/J3.2:How_to_use_the_Template_Manager|Template Manager: Customise Template]] view.</translate>
 +
::[[File:3x-template-manager-customise-template-toolbar-<translate><!--T:13-->
 +
en</translate>.png]]
 +
<translate><!--T:14-->
 +
*Provide a new name and click on Copy Template</translate>
 +
::[[File:3x-template-manager-customise-template-popup-copy-<translate><!--T:15-->
 +
en</translate>.png]]
 +
<translate><!--T:16-->
 +
*The template is completely copied. This includes styles and all the template files.</translate>
  
'''both'''
+
<translate>===Manually=== <!--T:17--></translate>
You are given the choice of editing "html" and "css."
+
<translate><!--T:18-->
+
*Create a new ''/templates/my_template'' directory.
[[CSS]] stands for cascading style sheets. This controls many elements of the look and feel of your site.
+
*Copy the contents of the original ''template'' directory to the ''my_template'' directory.
[[HTML]] is the file that controls where positions are defined and positioned. Other than that, it should be noted that, with a few exceptions, what is in the .css and what is in the HTML files largely depends on the approach of the tempate designer.
+
*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''.</translate>
  
One common change is to use your own graphic/image. Graphics are linked to in the HTML file. Simply change the reference to the image of your choice. Keep in mind that it if it is a different size than the original image this may change the appearance of the site in unexpected ways.
+
<translate><!--T:19-->
 +
<syntaxhighlight lang="xml"><name>My_Template</name></syntaxhighlight>
  
<noinclude>[[Category:FAQ]]
+
<!--T:20-->
[[Category:Administration FAQ]]
+
<syntaxhighlight lang="xml"><language tag="en-GB">en-GB.tpl_my_template.ini</language>
[[Category:Getting Started FAQ]]
+
<language tag="en-GB">en-GB.tpl_my_template.sys.ini</language></syntaxhighlight></translate>
[[Category:Installation FAQ]]
+
 
[[Category:Upgrading and Migrating FAQ]]
+
<translate><!--T:21-->
[[Category:Version 1.5 FAQ]]
+
<syntaxhighlight lang="xml">
[[Category:Template Management]]</noinclude>
+
<param name="template_header" type="folderlist" directory="templates/my_template/styles/header" default="" label="Header Templates" description="HEADER TEMPLATES DESCRIPTION" />
 +
<param name="template_background" type="folderlist" directory="templates/my_template/styles/background" default="" label="Background Templates" description="BACKGROUND TEMPLATES DESCRIPTION" />
 +
<param name="template_elements" type="folderlist" directory="templates/my_template/styles/elements" default="" label="Primary Elements" description="PRIMARY ELEMENTS DESCRIPTION" /></syntaxhighlight></translate>
 +
 
 +
<translate>==== Discover the New Template ==== <!--T:22--></translate>
 +
<translate><!--T:23-->
 +
When manually copying a template, the new template must be introduced to your Joomla site through the discovery process.</translate>
 +
 
 +
<translate><!--T:24-->
 +
*Go to {{rarr|Administrator,Extensions,Extension Manager,Discover}}
 +
*Click the Discover icon.
 +
*Select your new template.
 +
*Click Install.</translate>
 +
 
 +
<translate><!--T:25-->
 +
If successful, the new template will now be available in {{rarr|Administrator,Extensions,Template Manager}}</translate>
 +
 
 +
<translate><!--T:26-->
 +
*Make the new template the default template.
 +
*View the site to verify it.</translate>
 +
 
 +
<translate>== Finding Errors == <!--T:27--></translate>
 +
<translate><!--T:28-->
 +
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.</translate>
 +
 
 +
<translate><!--T:29-->
 +
Joomla contains some useful debugging tools. To see what is happening while working on a site, there are three settings that you should change.</translate>
 +
 
 +
<translate><!--T:30-->
 +
# ''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'')</translate>
 +
 
 +
<translate><!--T:31-->
 +
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.</translate>
 +
 
 +
<noinclude>
 +
<translate><!--T:32-->
 +
[[Category:Template Development]]
 +
[[Category:Template Development FAQ]]
 +
[[Category:Template Reference]]
 +
[[Category:Tutorials]]</translate>
 +
</noinclude>

Latest revision as of 11:56, 7 November 2014

Other languages: English 100% • ‎español 100% • ‎français 100% • ‎Nederlands 100%

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.

Contents

Before You Begin

Before you start hacking away at a default installed template or any other template you may have installed, remember that any updates of the Joomla core files may contain new copies of the default Joomla templates. Similarly, editing an installed template means you may have to re-install it to reset it to the original state at installation.

Unless you take steps to protect your work, modifications could be lost when upgrading Joomla. Likewise, you may want to preserve an installed template in case you have any problems with modifications to it.

There are options in the Template Manager to Duplicate and Copy an existing template style or the actual template and template files. This page refers to the methods available to make a full copy of your template. This includes the style and all the template files of a template.

Tip-icon.png
A Tip!

Template Style and Template copying are not the same. You can make a copy of the template style but you are not protected from overwriting the actual template files. Style copying simply adds another entry made in the _template_styles table of the database. This is useful is you want to check a web site design with different fonts, colors, widths or logos if these template style parameters exist. The template files are not duplicated into another uniquely-named directory and they will be overwritten during an upgrade.

Copy the Template

To preserve your changes you need to Copy the template with all its files and styles. This procedure makes references to creating a full copy (an exact duplicate) of the template including all the files. In order to make a copy, you must be on the Customise Template view.

There are two methods available for accessing the Template Manager: Customise Template. The Customise Template interface allows for editing the actual code found in the template files, creating template overrides and template file manipulation.

One-Click or Switch to Template View

30-Template-manager-template-styles-view-1-en.png

Tip-icon.png
A Tip!

Styles column refers to changing the available parameters of a template, such as color, font-color, logo, etc. These are dependent on the parameters a template maker made available and are a convenience for quick changes. Template - column refers to editing the actual template files.

To access the Template Customise feature:

  • Directly - Click the template name in the column Template
600
  • Indirectly - Styles will be highlighted, click on Templates below it which will turn the view to Template Manager:Templates, see image below.
30-Template-manager-template-style-view-en.png
  • Select the template you wish to modify which will change the view to Template Manager: Customise Template view

Customisation View

You should now be looking at the image below, Template Manager: Customise Template.

3x-template-manager-customise-template-en.png


Copy an Existing Template

The Easy Way

Create a new template by copying an existing template:

3x-template-manager-customise-template-toolbar-en.png
  • Provide a new name and click on Copy Template
3x-template-manager-customise-template-popup-copy-en.png
  • The template is completely copied. This includes styles and all the template files.

Manually

  • 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="template_header" type="folderlist" directory="templates/my_template/styles/header" default="" label="Header Templates" description="HEADER TEMPLATES DESCRIPTION" />
<param name="template_background" type="folderlist" directory="templates/my_template/styles/background" default="" label="Background Templates" description="BACKGROUND TEMPLATES DESCRIPTION" />
<param name="template_elements" type="folderlist" directory="templates/my_template/styles/elements" default="" label="Primary Elements" description="PRIMARY ELEMENTS DESCRIPTION" />

Discover the New Template

When manually copying a template, 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.

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.

  1. Administration > Site > Global Configuration > System > Debug Settings > Debug System > Yes (Default = No)
  2. Administration > Site > Global Configuration > System > Debug Settings > Debug Language > Yes (Default = No)
  3. 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.