Creating a basic joomla


Published on

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Creating a basic joomla

  1. 1. Creating a basic Joomla! template Unspecified errors have been reported with this page and it requires a technical review. Contents [hide]1 Introduction2 Setting up a directory structure3 Creating a basic templateDetails.xml file4 Creating a basic index.php file o 4.1 Begin o 4.2 Head o 4.3 Body Section  4.3.1 Module Positions o 4.4 End o 4.5 Custom Images o 4.6 Custom CSS5 Testing the template6 Packaging the template for installation o 6.1 Note to Mac OS X users7 ConclusionIntroductionThe purpose of this tutorial is to serve as an introduction to creating Joomla! templates. It will cover theessential files and code needed to create a basic template. The code is presented so it can be cut andpasted with very little modification needed.Setting up a directory structureTo make the most basic template, create a new folder in the templates folder. Name this folder afteryour template i.e. mynewtemplate.Using a 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 afile called template.css.
  2. 2. Although it is fine to place all your CSS code directly in your index.php file to start, many webdevelopers prefer to place their CSS code in a separate file that can be linked from multiple pages usingthelink tag. This may also shorten the loading time of your pages, since the separate file can becached.This is the most basic practical setup.Outline of folder and file structure: mynewtemplate/  css/  template.css  images/  index.php  templateDetails.xml This article is a small, well-defined item that could be completed by someone with a reasonable knowledge of the subject matter and a modest time commitment. If you would like to try writing this article youre welcome to do so. The subject may be self-evident, but if not then further details should be available on the discussion page. Please add {{inuse}} at the top of this page while editing. For other small, well-defined tasks, please look in the Cookie jar. Thank you.Creating a basic templateDetails.xml fileThe templateDetails.xml file is essential. Without it, your template wont be seen by Joomla!. Thefile holds key metadata about the template.The syntax of the file is different for each Joomla version.For , use the following:<?xmlversion="1.0"encoding="utf-8"?><!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN"""><installversion="1.5"type="template"> <name>mynewtemplate</name> <creationDate>2008-05-01</creationDate> <author>John Doe</author> <authorEmail></authorEmail> <authorUrl></authorUrl> <copyright>John Doe 2008</copyright> <license>GNU/GPL</license>
  3. 3. <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 and later, use the following version. Change version="1.6" into the version of your Joomla!installation.<?xmlversion="1.0"encoding="utf-8"?><extensionversion="1.6"type="template"> <name>mynewtemplate</name> <creationDate>2008-05-01</creationDate> <author>John Doe</author> <authorEmail></authorEmail> <authorUrl></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>
  4. 4. <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 bestapproach 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 dont know what they are calledyet - dont 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 thestandard templates.Creating a basic index.php fileThe 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 worksby adding Joomla code into module positions and the component section in your template. Anythingadded to the template will appear on all pages unless it is added to one of these sections via the JoomlaCMS (or customised code).This page will show the bare-bones code ready for you to cut and paste into your own design.BeginA Joomla 1.5+ template begins with the following lines:<?phpdefined(_JEXEC) or die(Restricted access);?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ""><html xmlns="" xml:lang="<?phpecho$this->language;?>" lang="<?phpecho$this->language;?>">The first line stops naughty people looking at your coding and getting up to bad things.The second line is the Document Type Declaration (DOCTYPE), which tells the browser (and webcrawlers) which flavor of HTML the page is using. The doctype used above is XHTML 1.0, which issupported rather well by most modern browsers. You can also decide to use HTML5, a newer version of
  5. 5. HTML that is largely backwards compatible, but contains many new features. To use HTML5, change thedoctype to<!DOCTYPE html>You should be aware that this will not work well in Internet Explorer 8 or earlier without a hack. You mightwant to investigate this situation and your clients wishes before deciding on which doctype you want touse.The third line begins our HTML document and describes what language the website is in. A htmldocument is divided into two parts, head and body. The head will contain the information about thedocument and the body will contain the website code which controls the layout.Head<head><jdoc:include type="head" /><link rel="stylesheet" href="<?phpecho$this->baseurl?>/templates/system/css/system.css" type="text/css" /><link rel="stylesheet" href="<?phpecho$this->baseurl?>/templates/system/css/general.css" type="text/css" /><link rel="stylesheet" href="<?phpecho$this->baseurl?>/templates/<?phpecho$this->template;?>/css/template.css"type="text/css" /></head>The first line gets Joomla to put the correct header information in. This includes the page title, metainformation as well as system JavaScript. The rest creates links to two system style sheets and to yourown style sheet (if its named template.css and is located in the css folder of your template directory.So if your temlate is in then the css files will goin Section<body><jdoc:include type="modules" name="top"/><jdoc:include type="component"/><jdoc:include type="modules" name="bottom"/></body>Amazingly, this will suffice! Yes, its a very basic layout, but it will do the job. Everything else will be doneby Joomla!. These lines, usually called jdoc statements, tell Joomla to include output from certain parts ofthe Joomla system. Note: you will need to ensure your menu is set to go into the "top" module position.Module Positions
  6. 6. Above, the line which says name="top" adds a module position called top and allows Joomla to placemodules into this section of the template. The type="component" line contains all articles and maincontent (actually, the component) and is very important. It goes in the centre of the template.Note: You can add your own module lines anywhere you want in the body, but you have to add acorresponding line to the templateDetails.xml file which sits alongside the index.php of your template.EndFinish it off - one last bit:</html>Custom ImagesIf you want to add any images to the template you can do so like this:<img src="<?phpecho$this->baseurl;?>/images/stories/myimage.png" alt="Customimage" class="customImage" />Here the baseurl variable will fill in the path to your template for you.Custom CSSYou can add custom css like this:<link rel="stylesheet" href="<?phpecho$this->baseurl?>/templates/<?phpecho$this->template;?>/css/styles.css"type="text/css" />Every file which is added must have a line in the templateDetails.xml file for the template.Full template source code:<?phpdefined(_JEXEC) or die(Restricted access);?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ""><html xmlns="" xml:lang="<?phpecho$this->language;?>" lang="<?phpecho$this->language;?>"><head><jdoc:include type="head" /><link rel="stylesheet" href="<?phpecho$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" />
  7. 7. </body></html>Testing the templateFind the template in the Template Manager, select it and click Default to make it the default template. In Joomla! 1.5, your new template will show up immediately in the Template Manager, accessiblevia Extensions -> Template Manager. + In Joomla 1.6, you first need to tell Joomla! that you have created a new template. This feature iscalled 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 andclick Install to install it. Now your template should show up in the Template Manager (Styles), accessiblevia Extensions -> Template Manager.HINT: there are a couple of ways you can preview your index page as you put it together, either insert thestyles into the head of the index page or directly link it to the style sheet you will be using temporarily. Youcan remove these links before packaging the file.Packaging the template for installationA directory with several loose files is not a convenient package for distribution. So the final step is tomake a package. This is a compressed archive containing the directory structure and all the files. Thepackage can be in ZIP format (with a .zip extension), in TAR-gzip format (with a .tar.gz extension),or in TAR-bz2 format (with a .tar.bz2 extension).If your template is in a directory mytemplate/ then to make the package you can connect to thatdirectory and use commands like: tar cvvzf ../mytemplate.tar.gz * zip -a -r *.*Note to Mac OS X usersNote to template developers using Mac OS X systems: the Finders "compress" menu item produces ausable ZIP format package, but with one catch. It stores the files in AppleDouble format, adding extra fileswith names beginning with "._". Thus it adds a file named "._templateDetails.xml, which Joomla1.5.x can sometimes misinterpret. The symptom is an error message, "XML Parsing Error at 1:1. Error 4:Empty document". The workaround is to compress from the command line, and set a shell environmentvariable "COPYFILE_DISABLE" to "true" before using "compress" or "tar". See theAppleDouble article formore information.
  8. 8. To set an environment variable on a Mac, open a terminal window and type:export COPYFILE_DISABLE=trueThen in the same terminal window, change directories into where your template files reside and issue thezip command. For instance, if your template files have been built in a folder in your personal directorycalled myTemplate, then you would do the following:cd myTemplatezip -r *ConclusionYou should now have created a template that works. It wont look like much yet. The best thing to do nowis start experimenting with the layout.Categories: Articles that require a review | Cookie jar | Template Development | Tutorials | Templates