Difference between revisions of "Creating a basic Joomla! template"

From Joomla! Documentation

m (JSplit template)
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{notice|Unspecified errors have been reported with this page and it requires a technical review. }}[[Category:Articles that require a review]]
+
{{version/tutor|1.5,1.6,1.7,2.5,3.0}}{{JSplit}}
 
== Introduction ==
 
== Introduction ==
  
Line 5: Line 5:
  
 
== Setting up a directory structure ==
 
== Setting up a directory structure ==
{{:Setting up a directory structure|Setting up a directory structure}}
+
To make the most basic template, '''create a new folder''' in the ''templates'' folder. Name this folder after your template i.e. ''mynewtemplate''.
{{:How to edit the files|How to edit the files}}
+
 
 +
Using your favourite text editor create the files <code>index.php</code> and <code>templateDetails.xml</code>.
 +
To keep things organized, make '''2 new folders''' called ''images'' and ''css''. Inside the ''css'' folder create a file called <code>template.css</code>.
 +
 
 +
Although it is fine to place all your [[CSS]] code directly in your index.php file to start, many web developers prefer to place their CSS code in a separate file that can be linked from multiple pages using the <code>link</code> tag. This may also shorten the loading time of your pages, since the separate file can be cached.
 +
 
 +
This is the most basic practical setup. Outline of folder and file structure:
 +
* mynewtemplate/
 +
** css/
 +
*** template.css
 +
* images/
 +
* index.php
 +
* templateDetails.xml
 +
 
 
== Creating a basic templateDetails.xml file ==
 
== Creating a basic templateDetails.xml file ==
{{:Creating a basic templateDetails.xml file}}
+
The <tt>templateDetails.xml</tt> file is essential. Without it, your template won't be seen by Joomla!. The file holds key [[Wikipedia:Metadata|metadata]] about the template.
 +
 
 +
The syntax of the file is different for each Joomla version.
 +
 
 +
For {{JVer|1.5}}, use the following:
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
 +
<install version="1.5" type="template">
 +
<name>mynewtemplate</name>
 +
<creationDate>2008-05-01</creationDate>
 +
<author>John Doe</author>
 +
<authorEmail>john@example.com</authorEmail>
 +
<authorUrl>http://www.example.com</authorUrl>
 +
<copyright>John Doe 2008</copyright>
 +
<license>GNU/GPL</license>
 +
<version>1.0.2</version>
 +
<description>My New Template</description>
 +
<files>
 +
<filename>index.php</filename>
 +
<filename>templateDetails.xml</filename>
 +
<folder>images</folder>
 +
<folder>css</folder>
 +
</files>
 +
<positions>
 +
<position>breadcrumb</position>
 +
<position>left</position>
 +
<position>right</position>
 +
<position>top</position>
 +
<position>user1</position>
 +
<position>user2</position>
 +
<position>user3</position>
 +
<position>user4</position>
 +
<position>footer</position>
 +
</positions>
 +
</install>
 +
</source>
 +
 
 +
For {{JVer|1.6}} and later, use the following version. Change <code>version="1.6"</code> into the version of your Joomla! installation.
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<extension version="1.6" type="template">
 +
<name>mynewtemplate</name>
 +
<creationDate>2008-05-01</creationDate>
 +
<author>John Doe</author>
 +
<authorEmail>john@example.com</authorEmail>
 +
<authorUrl>http://www.example.com</authorUrl>
 +
<copyright>John Doe 2008</copyright>
 +
<license>GNU/GPL</license>
 +
<version>1.0.2</version>
 +
<description>My New Template</description>
 +
<files>
 +
<filename>index.php</filename>
 +
<filename>templateDetails.xml</filename>
 +
<folder>images</folder>
 +
<folder>css</folder>
 +
</files>
 +
<positions>
 +
<position>breadcrumb</position>
 +
<position>left</position>
 +
<position>right</position>
 +
<position>top</position>
 +
<position>user1</position>
 +
<position>user2</position>
 +
<position>user3</position>
 +
<position>user4</position>
 +
<position>footer</position>
 +
</positions>
 +
</extension>
 +
</source>
 +
 
 +
So, as you can see, we have a set of information between markup tags (the <code><element></code>s). Your best approach is to cut and paste this into your <tt>templateDetails.xml</tt> file and change the relevant bits (such as <code><name></code> and <code><author></code>).
 +
 
 +
The <code><files></code> part should contain all the files that you use - you possibly don't know what they are called yet - don't worry, update it later. The <code><folder></code> element can be used to define an entire folder at once.
 +
 
 +
Leave the positions as they are - these are a common set so you will be able to switch easily from the standard templates.
  
 
== Creating a basic index.php file ==
 
== Creating a basic index.php file ==
 
{{:Creating a basic index file}}
 
{{:Creating a basic index file}}
{{:Basic template index file}}
+
 
 +
This leaves a final file of:
 +
<source lang="php">
 +
<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
 +
<!DOCTYPE html>
 +
<html xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
 +
<head>
 +
<jdoc:include type="head" />
 +
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/mynewtemplate/css/template.css" type="text/css" />
 +
</head>
 +
<body>
 +
<jdoc:include type="modules" name="top" />
 +
<jdoc:include type="component" />
 +
<jdoc:include type="modules" name="bottom" />
 +
</body>
 +
</html>
 +
</source>
  
 
== Testing the template ==
 
== Testing the template ==
{{:Testing the template}}
+
Find the template in the Template Manager, select it and click '''Default''' to make it the default template.
 +
 
 +
{{JVer|1.5}} In Joomla! 1.5, your new template will show up immediately in the [[Help15:Screen.templates.15|Template Manager]], accessible via Extensions -> Template Manager.
 +
 
 +
{{JVer|1.6}}+ In Joomla 1.6, you first need to tell Joomla! that you have created a new template. This feature is called ''Discover Extensions'' and can be accessed via Extensions -> Extension Manager -> Discover (i.e. the Discover ''tab''). Click '''Discover''' (i.e. the Discover ''button'') to discover your template, then select it and click '''Install''' to install it. Now your template should show up in the [[Help16:Extensions_Template_Manager_Styles|Template Manager (Styles)]], accessible via Extensions -> Template Manager.
  
HINT: there are a couple of ways you can preview your index page as you put it together, either insert the styles into the head of the index page or directly link it to the style sheet you will be using temporarily. You can remove these links before packaging  the file.
+
Note you can create your template outside of Joomla and simply install it like any regular extension.
  
Okay, since this section of the article is set up so I can't edit it, I will do the only other thing I can, which is add on to the end. In Joomla 1.7, you need to click the discover <i>tab</i>, and then click the discover <i>icon</i> in the top right for Joomla to discover the new template.
+
HINT: there are a couple of ways you can preview your index page as you put it together, either insert the styles into the head of the index page or directly link it to the style sheet you will be using temporarily. You can remove these links before packaging the file.
  
 
== Packaging the template for installation ==
 
== Packaging the template for installation ==
{{:Packaging_the_template}}
+
{{:Packaging_a_extension}}
  
 
== Conclusion ==
 
== Conclusion ==

Revision as of 16:29, 15 March 2013

Split-icon.png
Split Page into Specific Joomla! Versions - J2.5 and 3.x

It has been suggested that this article or section be split into specific version Namespaces. (Discuss). If version split is not obvious, please allow split request to remain for 1 week pending discussions. Proposed since 11 years ago.

Introduction[edit]

The purpose of this tutorial is to serve as an introduction to creating Joomla! templates. It will cover the essential files and code needed to create a basic template. The code is presented so it can be cut and pasted with very little modification needed.

Setting up a directory structure[edit]

To make the most basic template, create a new folder in the templates folder. Name this folder after your template i.e. mynewtemplate.

Using your favourite text editor create the files index.php and templateDetails.xml. To keep things organized, make 2 new folders called images and css. Inside the css folder create a file called template.css.

Although it is fine to place all your CSS code directly in your index.php file to start, many web developers prefer to place their CSS code in a separate file that can be linked from multiple pages using the link tag. This may also shorten the loading time of your pages, since the separate file can be cached.

This is the most basic practical setup. Outline of folder and file structure:

  • mynewtemplate/
    • css/
      • template.css
  • images/
  • index.php
  • templateDetails.xml

Creating a basic templateDetails.xml file[edit]

The templateDetails.xml file is essential. Without it, your template won't be seen by Joomla!. The file holds key metadata about the template.

The syntax of the file is different for each Joomla version.

For Joomla 1.5, use the following:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
<install version="1.5" type="template">
	<name>mynewtemplate</name>
	<creationDate>2008-05-01</creationDate>
	<author>John Doe</author>
	<authorEmail>john@example.com</authorEmail>
	<authorUrl>http://www.example.com</authorUrl>
	<copyright>John Doe 2008</copyright>
	<license>GNU/GPL</license>
	<version>1.0.2</version>
	<description>My New Template</description>
	<files>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<folder>images</folder>
		<folder>css</folder>
	</files>
	<positions>
		<position>breadcrumb</position>
		<position>left</position>
		<position>right</position>
		<position>top</position>
		<position>user1</position>
		<position>user2</position>
		<position>user3</position>
		<position>user4</position>
		<position>footer</position>
	</positions>
</install>

For Joomla 1.6 and later, use the following version. Change version="1.6" into the version of your Joomla! installation.

<?xml version="1.0" encoding="utf-8"?>
<extension version="1.6" type="template">
	<name>mynewtemplate</name>
	<creationDate>2008-05-01</creationDate>
	<author>John Doe</author>
	<authorEmail>john@example.com</authorEmail>
	<authorUrl>http://www.example.com</authorUrl>
	<copyright>John Doe 2008</copyright>
	<license>GNU/GPL</license>
	<version>1.0.2</version>
	<description>My New Template</description>
	<files>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<folder>images</folder>
		<folder>css</folder>
	</files>
	<positions>
		<position>breadcrumb</position>
		<position>left</position>
		<position>right</position>
		<position>top</position>
		<position>user1</position>
		<position>user2</position>
		<position>user3</position>
		<position>user4</position>
		<position>footer</position>
	</positions>
</extension>

So, as you can see, we have a set of information between markup tags (the <element>s). Your best approach is to cut and paste this into your templateDetails.xml file and change the relevant bits (such as <name> and <author>).

The <files> part should contain all the files that you use - you possibly don't know what they are called yet - don't worry, update it later. The <folder> element can be used to define an entire folder at once.

Leave the positions as they are - these are a common set so you will be able to switch easily from the standard templates.

Creating a basic index.php file[edit]

<translate> The index.php file becomes the core of every page that Joomla! delivers. Essentially, you make a page (like any HTML page) but place PHP code where the content of your site should go. The template works by adding Joomla code into module positions and the component section in your template. Anything added to the template will appear on all pages unless it is added to one of these sections via the Joomla CMS (or customised code).</translate>

<translate> This page will show the bare-bones code ready for you to copy and paste into your own design.</translate>

<translate>

Begin[edit]

</translate>

<translate> A Joomla template begins with the following lines:</translate>

<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html>
<html xmlns="https://www.w3.org/1999/xhtml/"
   xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >

<translate> The first line stops people looking at your coding and getting up to bad things.</translate>

<translate> The second line is the Document Type Declaration (DOCTYPE), which tells the browser (and web crawlers) which flavor of HTML the page is using. The doctype used above is HTML5, a newer version of HTML that is largely backwards compatible, but contains many new features. You should be aware that this will not work well in old browsers without a hack. You might want to investigate this situation and your clients' wishes before deciding on which doctype you want to use. However, this is used in Joomla Joomla 3.0 and higher.</translate>

<translate> The third line begins our HTML document and describes which language the website is in. An HTML document is divided into two parts: head and body. The head will contain the information about the document and the body will contain the website code which controls the layout.</translate>

<translate>

Head[edit]

</translate>

<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/system/css/general.css" type="text/css" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/css/template.css" type="text/css" />
</head>

<translate> The first line gets Joomla to put the correct header information in. This includes the page title, meta information as well as system JavaScript.</translate> <translate> The rest creates links to two system style sheets and to your own style sheet (if it's named template.css and is located in the css folder of your template directory. So if your template is in https://www.mysite.com/templates/my_template/ then the css files will go in https://www.mysite.com/templates/my_template/css/).</translate>

<translate>

Body Section[edit]

</translate>

<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>

<translate> Amazingly, this will suffice! Yes, it's a basic layout, but it will do the job. Everything else will be done by Joomla! These lines, usually called jdoc statements, tell Joomla to include output from certain parts of the Joomla system. Note: you will need to ensure your menu is set to go into the "top" module position.</translate>

<translate>

Module Positions[edit]

</translate>

<translate> Above, the line which says name="top" adds a module position called top and allows Joomla to place modules into this section of the template. The type="component" line contains all articles and main content (actually, the component) and is very important. It goes in the centre of the template.</translate>

<translate> Note: You can add your own module lines anywhere you want in the body, but you have to add a corresponding line to the templateDetails.xml file which sits alongside the index.php of your template.</translate>

<translate>

End[edit]

</translate> <translate> Finish it off - one last bit:</translate>

</html>

<translate>

Custom Images[edit]

</translate> <translate> If you want to add any images to the template you can do so like this:</translate>

<img src="<?php echo $this->baseurl; ?>/templates/<?php echo $this->template; ?>/images/myimage.png" alt="Custom image" class="customImage" />

<translate> Here the template variable will fill in the name of your template.</translate>

<translate>

Custom CSS[edit]

</translate>

<translate> You can add custom CSS like this:</translate>

<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template;?>/css/styles.css" type="text/css" />

<translate> Every file which is added must have a line in the templateDetails.xml file for the template, unless it resides in a sub-folder (which can be included in a <folder> element).</translate>


This leaves a final file of:

<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html>
<html xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/mynewtemplate/css/template.css" type="text/css" />
</head>
<body>
<jdoc:include type="modules" name="top" /> 
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>
</html>

Testing the template[edit]

Find the template in the Template Manager, select it and click Default to make it the default template.

Joomla 1.5 In Joomla! 1.5, your new template will show up immediately in the Template Manager, accessible via Extensions -> Template Manager.

Joomla 1.6+ In Joomla 1.6, you first need to tell Joomla! that you have created a new template. This feature is called Discover Extensions and can be accessed via Extensions -> Extension Manager -> Discover (i.e. the Discover tab). Click Discover (i.e. the Discover button) to discover your template, then select it and click Install to install it. Now your template should show up in the Template Manager (Styles), accessible via Extensions -> Template Manager.

Note you can create your template outside of Joomla and simply install it like any regular extension.

HINT: there are a couple of ways you can preview your index page as you put it together, either insert the styles into the head of the index page or directly link it to the style sheet you will be using temporarily. You can remove these links before packaging the file.

Packaging the template for installation[edit]

<translate>

Note on the Component Dependent Modules[edit]

</translate> <translate> Sometimes modules (or plugins and so on) use a component's models and helpers and such. On these occasions it would be nice to be able to package your module in a way that it gets uninstalled when the component itself gets uninstalled. This is called dependency management that has been desired in Joomla but hasn't been done yet. It is suggested that you follow the standards and use a package as described below. </translate>

<translate>

What is a Package?[edit]

</translate> <translate> A package is a extension that is used to install multiple extensions at one time. Use a package if you have, for example, a component and a module that are dependent upon each other. Combining them in a package will allow the user to install and uninstall both extensions in a single operation. Package extensions can be used with Joomla Joomla 2.5 and higher. </translate>

<translate>

How Do I Create a Package?[edit]

</translate> <translate> A package extension is created by zipping all .zip files of the extensions together with a .xml manifest file. For example, if you have a package composed of: </translate>

<translate>

  • component helloworld
  • module helloworld
  • library helloworld
  • system plugin helloworld
  • template helloworld

The package should have the following tree in your zip file: </translate>

 -- pkg_helloworld.xml
 -- packages <dir>
     |-- com_helloworld.zip
     |-- mod_helloworld.zip
     |-- lib_helloworld.zip
     |-- plg_sys_helloworld.zip
     |-- tpl_helloworld.zip
 -- pkg_script.php

<translate> The pkg_helloworld.xml could have the following contents: </translate>

 <?xml version="1.0" encoding="UTF-8" ?>
 <extension type="package" version="1.6" method="upgrade">
 <name>Hello World Package</name>
 <author>Hello World Package Team</author>
 <creationDate>May 2012</creationDate>
 <packagename>helloworld</packagename>
 <version>1.0.0</version>
 <url>http://www.yoururl.com/</url>
 <packager>Hello World Package Team</packager>
 <packagerurl>http://www.yoururl.com/</packagerurl>
 <description>Example package to combine multiple extensions</description>
 <update>http://www.updateurl.com/update</update>
 <scriptfile>pkg_script.php</scriptfile>
 <files folder="packages">
   <file type="component" id="com_helloworld" >com_helloworld.zip</file>
   <file type="module" id="helloworld" client="site">mod_helloworld.zip</file>
   <file type="library" id="helloworld">lib_helloworld.zip</file>
   <file type="plugin" id="helloworld" group="system">plg_sys_helloworld.zip</file>
   <file type="template" id="helloworld" client="site">tpl_helloworld.zip</file>
 </files>
 </extension>

<translate> When you zip this and install it, you will see that all extensions will be installed. The package will be visible in the extension list so that a user might uninstall all extensions contained in the package. </translate>

<translate> Remember to use the package uninstaller instead of individual subpackage uninstallers to avoid orphan extension entries in the extension manager. </translate>

<translate>

Id = <file id="not_arbitrary">[edit]

The id element in <file ..> tag is not arbitrary! The id= should be set to the value of the element column in the #__extensions table. If they are not set correctly, upon uninstallation of the package, the child file will not be found and uninstalled. </translate>

<translate>

Plugin "group" attribute[edit]

The group attribute is required for the package installer to locate the plugin for uninstall. Group refers to the <folder> name specified in the plugin manifest file.</translate>

<translate>

Manifest Filename and Packagename[edit]

The naming of the manifest file and the ability to uninstall the package file itself are closely related. The manifest file must have a pkg_ prefix. The remainder of the manifest name (without the .xml extension) is to be used as <packagename>. Or, the other way around, a package you want to identify as blurpblurp_J3 gets that as its <packagename> and should be in a manifest file named pkg_blurpblurp_J3.xml. Failure to do so will make it impossible to uninstall the package itself.</translate>

<translate> An optional <pkg_script.php> which contains a class pkg_<packagename>InstallerScript with public function postflight can be used. (This works in Joomla! 3.6 and later).</translate>

<translate>

Extension Tag[edit]

</translate> <translate> As of Joomla! 3.4, you should include method="upgrade" in the <extension> tag if you want your package to succeed in updating itself on subsequent installations.</translate>

<translate> The version attribute of the <extension> tag should be set to the minimum supported version of Joomla for this package. For example, if your package only supports Joomla! 3.2 and above, set this to 3.2.</translate>

<translate> Note: This version attribute is purely optional. It has no influence on Joomla's installation routine. As of Joomla 4, the version attribute has therefore been removed from all core extensions. See pull request 29960 on github.com</translate> <translate>

Extension Uninstall Dependency[edit]

</translate> <translate> As of Joomla! 3.7.0, a package extension can declare that its child elements cannot be uninstalled independently with a <blockChildUninstall>true</blockChildUninstall> element in the package manifest. If your package needs all its extensions to operate effectively, set this to true or 1. </translate>


Conclusion[edit]

You should now have created a template that works. It won't look like much yet. The best thing to do now is start experimenting with the layout.