Creating a basic Joomla! template

From Joomla! Documentation

OK, something has gone wrong here. I edited the "creating an index.php file" and it went wrong - renamed itself 404.shtml. It refused to allow editing of the "creating" file so I tried making a new one "create". Now I can't access either to edit them.

Yeah, okay, I know why this is happening. There is a mod_rewrite rule that looks for "index.php" and rewrites the URL in its SEF form. This fails if "index.php" appears as part of the page name and so you get redirected to 404.shtml which is MediaWiki's "page not found" page. I think the quick and easy fix is to simply avoid having "index.php" in page names. Chris Davenport 10:29, 2 May 2008 (EDT)

Adding it to the site[edit]

I found I needed to go to Extensions->Extension Manager->Discover to add the template module to the site before it would appear. Is that the correct way of doing it? Perhaps adding some instructions at the end for how to add the template to an existing site would be helpful.

Peeldog 16:46, 8 April 2011 (UTC)

A bit of craziness?[edit]

What's happening toward the bottom of this page after "Finish it off - one last bit:"? It seems like a bunch of code might have gotten accidentally pasted or something. Corsulian 14:36, 1 June 2008 (EDT)

That bunch of code is the full template source explained in this tutorial and was included from another page but not wrapped in a PRE element to preserve the white space. I fixed all affected pages. --CirTap (talkcontribs) 10:23, 2 June 2008 (EDT)

How to edit[edit]

I was going to make a basic proof reading change to the text, but all the edit screens do not show any text, only the headings between wouble curly brackets. Is this because I am new, or because I am not too swift??


How to edit[edit]

I was going to make a basic proof reading change to the text, but all the edit screens do not show any text, only the headings between double curly brackets. Is this because I am new, or because I am not too swift??


(sorry for the double post - veeerrry slow browser!)

It's because you're new. ;-) The titles in double curly brackets are links to "transcluded" pages; that is, other wiki pages that are being embedded in the page. If you scroll to the bottom of the edit page you will see a list of the transcluded pages (they're called "templates" in wiki parlance; not to be confused with Joomla templates of course). If you click on one of those links you will be taken to the page with the text on it. From there you can click "Edit" and make your changes. For more information about using the wiki see: Help:Contents. Chris Davenport 12:31, 21 August 2008 (EDT)

Thanks Chris - thought it was something like that.

index.php header stylesheet[edit]

I'm new to Joomla! and still trying to get my head around the templates. Thanks to the author(s) so far on a clear and concise tutorial on a basic template.

I was just wondering if the following:

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

would not be better served as:

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

Regards Pierre

Is doctype "transitional" really neccessary within joomla templates?[edit]

Layout of modern templates usually try to use stricter definitions like "-//W3C//DTD HTML 4.01//EN" or even "-//W3C//DTD XHTML 1.1//EN". I would prefer it, if developers try to succeed with these w3c recommendations.

This is a user question, because i don't know the dependencies on joomla code

regards gorgonz

You can use whatever DocType you like in your template. However, bear in mind that all your components and modules will also need to be Strict-compliant if you use Strict in your template. You should only use Strict if you can guarantee that that will happen. This includes "user-generated" content, so you need to be certain that the WYSIWYG editor is also outputting Strict code too. It is for that reason that the core templates are set to the more conservative Transitional. Chris Davenport 17:30, 1 September 2009 (UTC)


Why is $this->baseurl used when it is invalid and doesn't work in the context of index.php template files? From my understanding it should be JURI::root(). If you try and use $this->baseurl in an index.php template file, you will find that nothing happens. --Vcardillo 17:24, 1 September 2009 (UTC)

Looks like there was a code change and nobody noticed. ;-). Would you like to help us out and amend the page appropriately? Thanks. Chris Davenport 17:32, 1 September 2009 (UTC)

I might be wrong. I am reading through this thread: and trying to figure out whether $this->baseurl should be used, or JURI::base() should be used. --Vcardillo 17:41, 1 September 2009 (UTC)

Okay, I delved into this a bit further. $this->baseurl is still valid and is equivalent to JURI::base( true ). So the tutorial is correct as far as I can see. You can find further information on JURI::base() here: JURI/base. You'll see I've added a note on that page. Thanks for pointing it out. Chris Davenport 18:08, 1 September 2009 (UTC)

I still don't think things are right. Sometimes the method returns a trailing slash, and sometimes it doesn't? Doesn't this make it impossible to properly code a template file? You never know if this method is going to end with a slash or not, so how can you properly and safely reference images or JS files? You could end up with a double slash. --Vcardillo 18:22, 1 September 2009 (UTC)

I checked your corrections to JURI/base and they do seem to be correct. Well done. $this->baseurl will behave consistently (ie. it will never add a trailing slash) because it is explicitly set to JURI::base(true). You can see that in /libraries/joomla/application/component/view.php around line 178. Chris Davenport 20:12, 1 September 2009 (UTC)

Great. Thanks for the help and confirming! This all makes much more sense now. $this->baseurl would seem to be the best practice. --Vcardillo 22:22, 1 September 2009 (UTC)

Some Additional File Layout Notes[edit]

Here are some more topics for inclusion:

(1) Template style overrides for "component.php", "error.php", "offline.php", and other custom templates for "tmpl" query parameters. By default: - the error page (the "404 component not found" page) displays a default template located in /templates/system/error.php - the component page (what displays when "tmpl=component" is supplied in the query string) displays a default template located in /templates/system/component.php - the offline page (what displays when the site is set to "offline" in the global configuration) displays a default template located in /templates/system/offline.php

Each of these can be overridden in a custom template by placing a file of the same name in the root of the individual's template directory. For example, to supply a custom error page for a template called "myfirsttemplate", an error.php file would be placed in /templates/myfirsttemplate/error.php. Likewise, to supply a custom offline page, one would place an error template in /templates/myfirsttemplate/offline.php. In addition, any other type of template can be created to be displayed when the URL is formed with the "tmpl" query string parameter (e.g., by placing a template in the templates base directory with the same name - such as /templates/myfirsttemplate/someothertemplate.php.

(2) Component and module overrides can be supplied for any component or module which makes use of Joomla! 1.5 mvc system's tmpl file (/components/com_mycomponent/views/someview/tmpl/default.php). To provide an alternate layout / template for a component, such as the contact (com_contact) component's contact detail view we can look at the component's natural front end layout (/components/com_contact/views/contact/tmpl/default.php) and create a file in the template directory at /templates/mytemplate/html/com_contact/contact/default.php which overrides the component's default.php file. This is really useful for creating custom views of components without changing the components themselves. A module's display can be modified in the same way, e.g., the /modules/mod_feed/tmpl/default.php file can be overridden by creating /templates/mytemplate/html/mod_feed/default.php.

(3) Module styles can be added such that using <jdoc:include type="modules" name="module_position" style="mynewstyle" /> would employ an alternate module content layout. For example, to create a new module style "mynewstyle" which displayed module content in a double bordered box we could create a new file /templates/mytemplate/html/modules.php with contents:

function modChrome_mynewstyle($module, &$params, &$attribs) {
   if (!empty($module->content)) {
   <div style="border:1px solid #000;padding:3px;" class="moduletable<?php echo $params->get('moduleclass_sfx'); ?>">
      <div style="border:1px solid #000;padding:3px;">
      <?php echo $module->content; ?>

The formatting of the function name determine the style name (or visa versa). For example, for a new style "someotherstyle" the function would be named "function modChrome_someotherstyle(..."

--Cullen 05:01, 11 September 2009 (UTC)


where does this file suddenly come from? please fix the mess. Saddam 13:19, 12 November 2010 (UTC)

template manager[edit]

in the end, it should be explained how make the template appear in the template manager. Saddam 13:35, 12 November 2010 (UTC)

Creating a basic index.php file[edit]

Under "Creating a basic index.php file" I came across this note:

"either insert the styles into the head of the index page or directly link it to the style sheet you will be using temporarily."

This kind of advice would probably be useful to someone who already knew what he was doing. IOW, if someone is savvy enough to understand it, he's probably unlikely to ever stumble across this page.

It's like a new kid in town who wants to know how to get to the candy store, so he asks a resident, who tells him, "You go down to the old Johnson place and turn left." Well, the only direction in that that one could assume the questioner to know, would be "turn left". If he knew where "the old Johnson place" was, he probably would not be asking directions to begin with.

In the Note to the index.php section, if I knew what styles were, what the index page was, and how to insert those styles into the as yet unexplained "head", I would likely not be on this page to begin with. Likewise, I am not aware that I am using a "style sheet" nor why I should, never mind how I might link it, temporarily or otherwise.

These things don't necessarily have to be enlarged upon right here in this document, but, we are using html, are we not? How about linking that note to a page explaining what the heck the guy's talking about? That way, if it's "common" knowledge (but not universal knowledge, like "turn left"), those who need further explanation can get it without forcing the more knowledgeable among us to wade through familiar territory, and those like me, who are just learning this stuff, could learn the basics as we go.

Ragtopcaddy 19:41, 14 February 2011 (UTC)

Why when I click edit "Testing the Template" nothing in that section of the article shows up?[edit]

This is really weird. Jaguar7 13:33, 23 November 2011 (CST)

It's not that weird. This page is written using the modular documentation method (see JDOC:Modular documentation). This means that the content you see under that heading is actually on another page, in this particular case Testing the template. Perhaps you could indicate what you'd like to change? This page needs some clarification and the chunks might need to be reorganized and/or renamed. Mvangeest 14:15, 23 November 2011 (CST)

Possible error in a line in the article[edit]


The article describes how to create the <body> section in the index.php-file. This is the code the article gives:

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

Instead of "bottom", shouldn't it be "footer" here? I had to change this at least in my index.php to make the template work.


Bonjour Jørgen

You're right BUT that show (AFAIK) that you're using the method to create a 1.5 template what is NOT the right way. pay attention to adapt your template to the specificities of the 3.x versions. This page requires anyway a complete overhaul.


(MATsxm (talk) 06:53, 5 July 2016 (CDT))