The Joomla! Community Magazine™

Using the Twitter Bootstrap Framework to build a responsive Joomla! Template from Scratch

Written by | Wednesday, 01 August 2012 00:00 | Published in 2012 August
In this article we want to look under the hood of the Joomla template system to understand the basics. Creating a template from scratch is not rocket science. When you are building a website you always need to decide whether it is better to create a template on your own or to buy one. Besides of these two options you can also modify an existing template. To be able to make a useful decision you need to understand the process of creating a Joomla template.

Templates in Joomla

Joomla consists of a frontend (the website) and a backend (the administration interface). Both parts have their own templates. They are stored in the folders

  • /templates - Frontend
  • /administrator/templates - Backend

Each template has it's own folder. In Joomla 2.5 you'll find two preinstalled non responsive templates (Beez 2 and 5) and one template framework (Atomic)

  • /templates/atomic
    Atomic a kind of an uncommon template framework
  • /templates/beez_20
    Beez 2 is the Joomla standard template.
  • /templates/beez5
    Beez 5 is the HTML5 version of Beez 2
  • /templates/system
    In this folder Joomla stores all the files that are common for all the templates, e.g. the Offline and the Error page.

The administrator folder looks the same

  • /administrator/templates/bluestork
    Bluestork is the default standard administrator template
  • /administrator/templates/hathor
    Hathor is an optional administrator template. It is accessible and colours are customizable.
  • /administrator/templates/system
    In this folder Joomla stores all the files that are common for all the templates, e.g. the Error page.

How to create a new Template?

You have three options for creating a new template

  1. start from scratch with creating a folder and all the necessary files
  2. install a starter theme and modify it
  3. copy an existing template and modify it

In this chapter we want to try option one. We'll create a responsive frontend template based on the Twitter Bootstrap framework for Joomla 2.5 from scratch. I'll keep it as simple as possibible. The aim of this chapter is to understand Joomla's template structure. It's quite easy to make it more and more pretty and complicate afterwards :)

Template name

First of all we need a name for our template. The name will appear in XML files, the database, the webservers files system and several caches. Avoid special characters and blanks in the name. I'll call the template cocoate.

Files and Folders

Create a /templates/cocoate folder.

In the folder we need the following files and a subfolder css

  • /templates/cocoate/index.php
  • /templates/cocoate/templateDetails.xml

index.php

<?php
defined('_JEXEC') or die;
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
<head>
<jdoc:include type="head" />
</head>
<body >
<jdoc:include type="modules" name="top" style="xhtml" />    
<jdoc:include type="modules" name="breadcrumbs" style="xhtml" />
<jdoc:include type="modules" name="left" style="xhtml" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="right" style="xhtml" />
<jdoc:include type="modules" name="footer" style="none" />    
</body>
</html>

Listing 1: index.php

The index.php file is the "page" template, the "big picture". Inside this file all the bits and pieces (CSS, JavaScript, Joomla content) were loaded. In our example I just loaded the Joomla content with the <jdoc:include ...> command. It contains the head, the component content and the module content depending on the postion of the module (What is a module?).

templateDetails.xml

This is the most important file in a template. It is the manifest, or packing list file that includes a list of all the files or folders that are part of the template. It also includes information such as the author and copyright. Without this file, Joomla wil not find your template. The positions are the module positions that are already mentioned in the index.php file. You can create as many positions as you want. So far, there is no naming standard in Joomla.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.6//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.6/template-install.dtd">
<install version="2.5" type="template" method="upgrade">
    <name>cocoate</name>
        <creationDate>2012-07-17</creationDate>
    <author>Hagen Graf</author>
    <authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
    <authorUrl>http://cocoate.com</authorUrl>
    <copyright>Copyright (C) 2012 cocoate</copyright>
    <version>1.0</version>
    <description><![CDATA[
    <p>cocoate is a template exercise from scratch.<p>
    ]]></description>
    <files>
        <filename>index.php</filename>
        <filename>templateDetails.xml</filename>
        <folder>css</folder>
    </files>
    <positions>
        <position>top</position>
        <position>breadcrumbs</position>
        <position>footer</position>
        <position>left</position>
        <position>right</position>
        <position>footer</position>
    </positions>
</install>

Listing 2: templateDetails.xml

Discover and install your template

After creating the two files and the folders, we have to discover and install the template. Since Joomla 1.6, a template is "registered" in the _extensions database table. Go to Extensions -> Extensions manager -> Discover. Click the Discover Icon on top. You will see your freshly created template (Figure 1). Check the template and click on install (Figure 2).

Discover

Figure 1: Discover the cocoate template

Install Template

Figure 2: Install the cocoate template

During the install process, there has been automatically created also a template style. Check this style (Extensions -> Template Manager) and make it the default template style (Figure 3).

Default Template

Figure 3: Choose the cocoate template as default template

Visit your website and have a first look at your template (Figure 4).

First look

Figure 4: Your website with your new template

When you play around and open the site also with your mobile device, you'll notice that it is fully responsive :) But there is no real "User Interface", this is not so pretty and we have no images so far.

Integrate Twitter Bootstrap Files

Now it is necessary to integrate Twitter Bootstrap before we continue. At the time I wrote this text, the version 2.0.4 was the latest release.
In the example I use the Twitter Bootstrap package that comes with a documentation (http://twitter.github.com/bootstrap/) (Figure 5). Download and unzip the package (https://github.com/twitter/bootstrap/zipball/master) and copy the folders /assets into the /template/cocoate folder (Figure 6).

Twitter Bootstrap Download

Figure 5: Twitter Bootstrap website

Assets Folder

Figure 6: copy or move assets folder

The assets folder contains the necessary CSS and JavaScript files and it comes with predefined images and icons.

Later on, when you are more experienced with Joomla templates, you can put the necessary Twitter Bootstrap files into a different folder. For our example it is easier to use the /assets folder.

Integrate Twitter Bootstrap into your template

Twitter Bootstrap comes with three example templates called hero, fluid and and starter-template. You can check them by clicking on the files in the /example folder.
Our aim is to combine the Joomla related commands with one of these examples. For the example I chose the fluid template (fluid.html).

The /templates/cocoate/index.php contains all the necessary Joomla parts. We need to create a mixture of both parts, let's start with a few key elements we need in the file:

<?php
defined('_JEXEC') or die;
// detecting site title
$app = JFactory::getApplication();
?>

This is php code and the typical start of a Joomla template. The object $app contains useful data about your Joomla, e.g. the name of your website.

<!DOCTYPE html>
<html lang="en">

This doctype is the HTML5 version and comes from the Twitter Bootstrap example.

In the <head> section we have to create the Joomla Metatags via a <jdoc> command and integrate the Bootstrap files. 

<head>
    <meta charset="utf-8">
    <jdoc:include type="head" />
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
    <link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/assets/css/bootstrap.css" type="text/css" media="screen" />
    ...
    <!-- ... more Bootstrap files ... -->
    ...
    <link rel="apple-touch-icon-precomposed" href="/<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/assets/ico/apple-touch-icon-57-precomposed.png">
</head>

The <body> section can be mostly copied from the fluid.html example. It's important to embed the <jdoc> commands at the right place.
This is an example for the top menu. You have to place a menu module at the position top-menu and you can e.g. show the sitename from the $app object

<div class="navbar navbar-fixed-top">
  <div class="navbar-inner">
    <div class="container-fluid">
    ...
    <a class="brand" href="#"><?php echo $app->getCfg('sitename'); ?></a>
    <div class="nav-collapse">
      <jdoc:include type="modules" name="top-menu" style="none" />
    </div>
  </div>
</div>

The main page is located in a so called "Fluid Container". It has a grid system with 12 rows by default. We use 9 of them for the display of the Joomla component and 3 of them for a sidebar on the right side, called right. The right side should only be shown if there are modules availablabe.

<div class="container-fluid">
  <div class="row-fluid">
    <div class="span9">
      <div class="hero-unit">
        <jdoc:include type="component" />
      </div>
    </div><!--/row-->
  </div><!--/span-->
  <div class="span3">
    <?php if($this->countModules('right')) : ?>
    <div class="well sidebar-nav">
      <jdoc:include type="modules" name="right" style="none" />
    </div><!--/.well -->
    <?php endif; ?>
   </div><!--/span-->
 </div><!--/row-->
</div><!--/.fluid-container-->

The last pieces are the Twitter Bootstrap JavaScript files at the end:

<script src="/<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/assets/js/jquery.js"></script>
<script src="/<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/assets/js/bootstrap.min.js"></script>
<script type="text/javascript">
        jQuery.noConflict();
</script>

As you see, the JavaScipt framework jQuery is loaded and also the minimal version of Twitter Bootstrap. You can see the content of the complete index.php files here /templates/cocoate/index.php.

The result is far from perfect (Figure 7) but it looks like a website and it's ... responsive. Try it with your browser window!

First Look

Figure 7: First look at the new template

Joomla Overrides

So far, everything was easy. Now the real work is starting. You have to override the default Joomla HTML output to get the full advantage of the Twitter Bootstrap Framework (Figure 8). If you don't know what I mean with Overrides, have a look here (for developers) and here (for users).

HTML Overrides

Figure 8: HTML Overrides

The Dropdown Menu

Joomla has no default menu with a dropdown option but Twitter Bootstrap offers dropdown support for menus and of course, we want to have exactly this feature in our template. It's quite hard to learn all the details about the HTML output of of modules in genaral. For this chapter, I suggest use existing overrides. Thanks to the work of  Gary Gisclair it is possible to download the Strapped template (http://hwdmediashare.co.uk/joomla-templates/116-strapped) and use the existing overrides. I just copied the whole /html folder into the /templates/cocoate folder.

I use the default Joomla example data and put the Main Menu Module to position top-menu. To match the correct CSS class I need to add " nav-dropdown" in the Menu Class Suffix (Extensions -> Module Manager -> Main Menu -> Edit -> Advanced Options) (Figure 9)

Main Menu

Figure 9: Main Menu - Advanced Options

It works!

The communication between Joomla and the Twitter Bootstrap is working. The Dropdown Menu is fully responsive and even the pictures will be automatically resized (Figure 10).

Second Look

Figure 10: Responsive Template based on Twitter Bootstrap

I installed this example template on my testsite too, so have a look at http://joomla25.cocoate.com.

Next steps

From my point of view, the next steps are

  • just playing around with other technologies (CSS, JS, HTML5, Joomla, PHP, Twitter Bootstrap)
  • have a look at the Twitter Bootstrap documentation
  • create Custom CSS
  • use Joomla Parameters to configure the template

Conclusion

I hope, you are now able to decide whether you want to go deeper into Joomla templating with the Twitter Bootstrap framework or just choose with a ready made template. This chapter is part of the Going Mobile with Joomla book which will be available for free as PDF as soon as possible.

Read 178321 times
Tagged under Designers
avatar
Kannan Naidu Venugopal Thursday, 02 August 2012
Thank you very much for this excellent tutorial
VOTES:0
avatar
Fantastic Article Hagen. Much appreciate for writing this. I am sure it will be very helpful for people learning like me and others.
Cheers !
VOTES:0
avatar
Thanks - Hopefully it's helpful. For me it's a beginning too :)
I'm not a designer and I'm playing around to find a good way to work with bootstrap ...
VOTES:0
avatar
Thank you! Really nice tutorial.
VOTES:-2
avatar
Last time Gavick was released the template for Joomla 3.0 based on bootstrap
joomla30.gavick.com/
VOTES:2
avatar
Thanks for all of the details! Now you can use Gantry v3.2.20+ and Twitter's Bootstrap Framework like RocketTheme is doing: www.rockettheme.com/joomla-templates/kirigami
VOTES:1
avatar
I have also been creating a template for Joomla 2.5 using Bootstrap, and have all 12 bootstrap jQuery plugins working - including scrollspy with joomla menus.
It is a starter template, ideally used as a starting point for a template design, although it can be used as-is - but it looks just like a default bootstrap site.
It is free to download from github github.com/KISS-Web-Design/kwd-j-bootstrap
And there is a working demo at kwd-j-bootstrap.stempsite.co.uk/
NOTE: I am still adding content to the demo site, but all the important stuff (scaffolding, components, javascript) is demonstrated.
VOTES:4
avatar
wow, sounds great!
I'll have a look and thanks for the hint
VOTES:-1
avatar
H
Very good tutorial
I've managed to make a template with it and even to make it some multi-direction (RTL/LTR) with
&quot; lang=&quot;language; ?&gt;&quot; dir=&quot;direction; ?&gt;&quot;

but...
I cannot manage to make the top nav-bar to change it's direction with the changing of he language

Any help will be appriciated

Eden Orion
VOTES:-1
avatar
Hi Eden, thanks for your comment. Unfortunately I have no &quot;out of the box&quot; solution :(.
I'm planning to write a few more articles concerning these kind of problems. If you find a working solution please keep me updated.
Hagen
VOTES:-1
avatar
Hallo Herr Graf,

gibt es diesen Artikel auch in Deutsch?
Ich habe versucht mir mit einem Übersetzungsprogramm Klarheit zu verschaffen. :-)
Da kommen die abenteuerlichsten Sachen raus.

Gruß Peter
VOTES:-1
avatar
This looks like a great article, could not have come at a better time for me, really want to design my own responsive web design template, cannot wait to get on with it, thanks.
VOTES:-1
avatar
Excellent tutorial.
Unfortunately it does not match my trial. I do not see the login on the right side at all - even after using exactly your index.php. And only when changing the menu position to top-menu do I see the menu at all. And after following the instructions for the bootstrap, there is no drop-down visible for me.
I am just learning how to write templates, so might be me.
VOTES:1
avatar
I'm having the same problem. I had to assign a login module from the backend and it showed up on the right. I can't get the menu to show up, though. Have you had any luck?
VOTES:0
avatar
Hello Hagen
I am trying to follow your tutorial but I seem to have done something wrong. My copyright is in the right position, the login mod is not showing, and I have no main menu.
Also I notice that in the index.php footer is shown twice.

top
breadcrumbs
footer
left
right
footer

If I add my own position to the index.php does it also have to be added to the templateDetail.xml file?
VOTES:1
avatar
&quot;If I add my own position to the index.php does it also have to be added to the templateDetail.xml file?&quot;

Adding those lines to the templateDetail.xml is just for comfort. If you do not add your position names to the templateDetail.xml, you won't be able to choose them from the list of positions for modules from the Joomla admin. However you still can type a position's name into the &quot;position&quot; field manually, so the position itself still be usable for modules.
VOTES:3
avatar
thank you this is revolutionary
VOTES:-1
avatar
Nice thanks. There is a 'space' before &quot;nav-dropdown&quot; (&quot; nav-dropdown&quot;) which I missed, incase anyone else is struggling with the Menu Class Suffix bit.
VOTES:1
avatar
Eden Orion wrote:
H
Very good tutorial
I've managed to make a template with it and even to make it some multi-direction (RTL/LTR) with
" lang="language; ?>" dir="direction; ?>"

but...
I cannot manage to make the top nav-bar to change it's direction with the changing of he language

Any help will be appriciated

Eden Orion

hi,

see this github resp:
github.com/AbdullahDiaa/Bootstrap-RTL

Thanks for your article, it will be useful for Joomla! users. Are there any sample template of this learning article?
VOTES:1
avatar
Rosemarie Villacorta Friday, 14 September 2012
excellent tuts! keep it up!
VOTES:-1
avatar
Awsome! Ive been trying to get a Joomla responsive design working 100% for a while..but could never get the menu working.. Thanks for the post!
VOTES:1
avatar
Great article. If you want to create a responsive Joomla template from scratch, this aritcle the place to start. If you've never built a Joomla template, you might struggle a little with this. There's a lot to understand. Also, the bootstrap framework provides an amazing set of tools.

Again, thanks Hagen for providing this valuable article.
VOTES:2
avatar
I follow your tut and it works okay up until the bit I copy the html file from the strapped template - then the article is duplicated - once in the hero class, and then underneath..

I can't work out why and it's driving me nuts, any ideas?

Thanks

Graeme
VOTES:1
avatar
I have already designed a template..can i integrate this into my existing template?
VOTES:1
avatar
thanks for sharing this article. it is very informative for beginners in responsive web development.
VOTES:0
avatar
Practical Tutorials Wednesday, 01 May 2013
Twitter bootstrap is a best framework for making a professional and good looking website. i done many projects in twitter bootstrap. The one which i like most is the practicaltuts.com See this site and tell me how much twitter bootstrap is powerfull.
VOTES:1
avatar
Eborio Linárez Tuesday, 21 May 2013
Thanks for the article, very well explained
VOTES:0
avatar
Sundaramoorthy M Monday, 03 June 2013
Let me know Twitter Bootstrap Framework is compatible for Joomla 3.0/3.1
VOTES:0
avatar
Great article but I can't get it to work at all... can you please provide a working link to your index.php file so I can see where I'm going wrong? I've tried everything and I can't get the bootstrap css to style any of the page at all.

Thanks
VOTES:0
avatar
/templates/cocoate/index.php. link is not working
VOTES:0
avatar
Nice tutorial.. I got the joomla template structure from your article. Thanks
VOTES:0
avatar
Thank you! Really nice tutorial very well explained
VOTES:1
avatar
Pretty sure the latest Joomla and Bootstrap versions have borked this tutorial. Very confusing and almost useless until it's updated.
VOTES:1