Magazine

Download
Launch
9 minutes reading time (1848 words)

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

237953 Hits
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)

  • /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" "https://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.

Some articles published on the Joomla Community Magazine represent the personal opinion or experience of the Author on the specific topic and might not be aligned to the official position of the Joomla Project

0
  Facebook   Twitter   LinkedIn   Pinterest
Tags:
Designers
Joomla! Websites: The Home Page of Champions

About the author

Hagen Graf

Hagen Graf

Hagen Graf
 

Comments

Already Registered? Login Here
No comments made yet. Be the first to submit a comment

By accepting you will be accessing a service provided by a third-party external to https://magazine.joomla.org/