Using the Twitter Bootstrap Framework to build a responsive Joomla! Template from Scratch
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)
Atomic a kind of an uncommon template framework
Beez 2 is the Joomla standard template.
Beez 5 is the HTML5 version of Beez 2
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
Bluestork is the default standard administrator template
Hathor is an optional administrator template. It is accessible and colours are customizable.
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
- start from scratch with creating a folder and all the necessary files
- install a starter theme and modify it
- 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 :)
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
<?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
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.
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).
Figure 1: Discover the cocoate 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).
Figure 3: Choose the cocoate template as default template
Visit your website and have a first look at your template (Figure 4).
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).
Figure 5: Twitter Bootstrap website
Figure 6: copy or move assets folder
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-->
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!
Figure 7: First look at the new template
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).
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)
Figure 9: Main Menu - Advanced Options
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).
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.
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
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.