Upgrade Your Joomla Site From Bootstrap v2.x To v3.x

Simplest template overrides for your Joomla! 3.3 website to make it compatible to Twitter’s Bootstrap 3.x

Rakesh Mali , 07 July, 2015

Bootstrap is one of the most popular front-end development frameworks available today. It speeds-up the development process offers several useful components like navigation, drop-downs, icons and much more. It is essentially a complete solution for creating responsive websites " you don’t need to be a CSS or HTML ninja to achieve a fluid layout with a 12-column grid.

The Bootstrap library has been part of the JUI since Joomla 3.0, which means that you can use the Bootstrap version 2.3.2 with Joomla 3. Bootstrap v.3 was released almost 2 years ago, but no update is available in Joomla! 3.3 to make it compatible. It means that if you are expecting to be able to use the latest version of Bootstrap with Joomla, you’ll be disappointed.

"Wait for the solution or create one to make the world better"


If you are using a framework based template (i.e. T3, Gantry etc) then just update your framework and bind template with it and you almost done, but if you are using a non framework based template this article will guide you in most of scenarios.

A basic template includes core components (i.e. com_content), modules, some layouts, paginations, component view without template wrapper etc.

Here is the list of files which needs to be overridden to make the template compatible to bootstrap 3.

Step 1 : Place below files in root/template/YOUR_TEMPLATE/html/:-

  1. components
    • com_contact
    • com_content
    • com_search
    • com_tags
    • com_users
    • com_weblinks
  2. Overrides the layouts
  3. <li>Modules
        <ul style="list-style-type: lower-latin;"><li>mod_breadcrumbs</li>

Step 2 : Place below file in root/template/YOUR_TEMPLATE/ :-

  1. component.php

For migration related issue following link will be helpful for you

Bootstrap Migration: http://getbootstrap.com/migration
FontAwesome Migration: https://github.com/FortAwesome/Font-Awesome/wiki/Upgrading-from-3.2.1-to-4

Problem while overriding :

While overriding we have found that Joomla has done some html code in the core files (like bootstrap accordion and modal popup HTML) and some icon’s name. As fontAwesome has now the class name with “fa-” but not with “icon-”.

To overcome from this issue we have decided to override these and created an installable system plugin which was capable to manage this problem.

These three core files have been overridden and put into : template/site/SAMEPATH-AS-THE ACTUAL-PATH

  1. bootstrap.php [Path: libraries/cms/html/bootstrap.php]
  2. icons.php [Path: libraries/cms/html/icon.php]
  3. jquery.php [Path: libraries/cms/html/jquery.php]

Download this system plugin and template override freely:

Now, it is time to go live

A Website may have many pages and it might not be possible to do changes in all the pages in one go. So we decided to do it in chunks and utilize the Joomla menu item IDs to go live easily.

We have followed these steps :

  • Created another folder for bs3 css (i.e. bootstrap 3) into the css folder of the template i.e. created a folder named as bs3 into it and placed all bs3 css files to here.

  • Created another folder for bs3 js into the js folder of the template i.e. created a folder named as bs3 into it and placed all bs3 and latest jquery js files to here.

  • Created an array (i.e. $bs3pages) into index.php. Now whenever we updated or moved any page to BS3, we add the menu id for that webpage into this array.

  • Included BootStrap 3 framework by checking if the Item_Id exist in the array (i.e. $bs3pages) otherwise the default will be bootstrap 2 for all pages.

All the above scenario can be understood like this:

if ($isBS3):
 //including bootstrap version 3
 $document->addStyleSheet('templates/' . $this->template . '/css/bs3/bootstrap.min.css');
 $document->addScript('templates/' . $this->template . '/js/bs3/jquery.min.js');
 $document->addScript('templates/' . $this->template . '/js/bs3/jquery-migrate.min.js');
 $document->addScript('templates/' . $this->template . '/js/bs3/bootstrap.min.js');
 //default bootstrap version 2
 $document->addStyleSheet('templates/' . $this->template . '/css/bootstrap.min.css');

Now we have updated many pages by following the above process.

Share your feedback in the below comment section. What do you think about this process? Do you follow any other approach to do this?

blog comments powered by Disqus