The Nitty-Gritty: Theme Improvements and Bootstrap in Liferay 6.2

With the release of Liferay 6.2, there have been a few questions regarding Bootstrap as well as general theme changes, and I'd like to take a minute to go into more details about what we've added, but also some of the rationale for some of the decisions.

Jorge's discussed a lot of the benefits, and the feedback we've gotten from the community has definitely been great.

If I had to sum-up, here are the most common questions I've gotten from developers about Bootstrap in 6.2:

  • Why did you choose version 2.3.2 instead of 3?
  • How do I use my Bootstrap theme?
  • Do you support Bootstrap's JavaScript plugins?
  • Why do all of the Bootstrap rules have .aui in front of them?

You may in fact have wondered those same things. Or maybe you didn't, but now that I've mentioned it, it's eating a hole in your brain. In order to alleviate your burning curiosity, I'll answer these questions first.

Why did you choose version 2.3.2 instead of 3?

We have been following Bootstrap 3's development since it was first announced in December of 2012, so we knew it was coming and had been discussing it while we were working on the Alloy and Liferay portions of converting over to it. Basically, the reason why we didn't use Bootstrap 3 comes down to 2 reasons:

  1. It was released on August 19th, 2013, roughly a month and a half before we were planning on releasing. Trying to cram it in at the last minute would have led to nothing but major bugs, weeping, gnashing of teeth, etc.
  2. It completely dropped support for IE7 and below. While in Liferay 6.2 we provided limited support for IE7 and below, it's just not feasible yet for this version to completely drop support for everyone across the board.

Hopefully that makes sense, and technically, you could still use Bootstrap 3 in your own theme and portlets (I'll go more into how this may be possible below).

How do I use my Bootstrap theme?

A common case is that someone has taken a generated theme (from a site such as Bootswatch) and want to use it inside of Liferay. If you're a theme developer, here's the easiest way you could accomplish that. I'm assuming you're using the plugins SDK and are familiar with placing your files in the _diffs/ directory):

  1. Inside of your theme's _diffs/css/ directory, create a file called aui.css.
  2. Open the aui.css file and do a find/replace with the following values: find: ../img/ replace: ../images/aui/ (and of course, deploy your theme).

This will use the default bootstrap icons, so there may be one or two that we have added that may not show up for you. If you'd like to use our version of FontAwesome (so you can use resolution independent icons as well), go ahead and paste this code inside of your _diffs/css/custom.css:

$FontAwesomePath: "aui/alloy-font-awesome/font" !default;

@import "aui/alloy-font-awesome/scss/variables";
@import "aui/alloy-font-awesome/scss/mixins-alloy";
@import "aui/alloy-font-awesome/scss/path-alloy";
@import "aui/alloy-font-awesome/scss/core";

body {
    @import "aui/alloy-font-awesome/scss/bootstrap";
    @import "aui/alloy-font-awesome/scss/extras";
    @import "aui/alloy-font-awesome/scss/icons-alloy";
    @import "aui/alloy-font-awesome/scss/icons-alloy-extra";

Do you support Bootstrap's JavaScript plugins?

We are only using the Bootstrap CSS and HTML conventions, but not any of their JavaScript. One reason is because Bootstrap uses jQuery and we use AlloyUI, and loading multiple JS libraries is just an overall bad practice. However, we did create equivalents for most of the Bootstrap JS components. For instance, we have a Modal, Tooltips, Pagination, Popovers, Tabs, and more. If there are ones you would like, please let us know, and we'll definitely prioritize getting them in :)

Why do all of the Bootstrap rules have .aui in front of them?

This is one of those changes that doesn't seem like much, but is actually really powerful.

With any framework, there's always a balancing act that involves juggling between simplicity and flexibility. Mnay of the issues we would see frequently in previous versions of Liferay were issues where our assumptions in making things easier could make it harder for theme developers to customize the portal.

Bootstrap is a very opinionated framework, which is what many people love, and many people can be frustrated by.

Previously, we always prefixed our CSS classes with .aui-, which is by far the safest. But this seemed wrong to do with Bootstrap's CSS classes. For one thing, it made it so that you couldn't easily just copy/paste the examples from the Bootstrap documentation and use it.

What we decided to do instead was to place a selector of .aui before all of Bootstrap's rules, so that the rules look like .aui .btn, etc.

What this does is allows you to not only easily remove Bootstrap from affecting the page, but even allows you to only apply Bootstrap selectively to different portions of the page (and this applies to Bootstrap's normalize.css rules as well).

For instance, let's imagine you want to only apply Bootstrap to the portlet's, but not touch anything else on the page. You would simply remove the aui CSS class from the $root_css_class variable, and edit your portlet.vm file and add it there.

You can take this CSS class and apply it anywhere (maybe you want everything only in one specific layout column, or only on one specific page, etc).

This is actually really exciting for theme developers and system integrators, but also allows casual users the ability to use Bootstrap without having to do any crazy workarounds.

What else is new in 6.2?

Bootstrap is completely controllable from the theme level

In earlier versions of Liferay, we included the Alloy CSS on the portal level. This led to issues such as having a reset.css being loaded from the theme, and one loaded from Alloy (and since it was on the portal level, it wasn't very easy to remove it without causing havoc on the rest of the CSS).

However, in 6.2, we've made it so that the portal looks for the CSS from the theme (we assume your theme has an aui.css file). What's great about this is that we also include the SCSS source, so you can control only specific variables or override specific files if you wanted to. For instance, if you wanted to customize specific files (say _thumbnails.scss) you could overwrite just that file. Or if you needed full control and wanted your version of Bootstrap to only have some bare minimum of button and form css, you can do that as well (though not necessarily recommended, as there are items in the portal that might be relying on other pieces of the framework).

An easier way to do media queries

We have also added a mixin called "respond-to" that allows you to easily target certain types of devices without having to remember the media queries. For example:

/* will only style phone displays smaller than 768px */
@include respond-to(phone) {
    body { background: red; }

/* will only style phone and tablet displays smaller than 980px */
@include respond-to(phone, tablet) {
    body { background: blue; }

/* will only style tablet and desktop displays greater than 768px */
@include respond-to(tablet, desktop) {
    body { background: green; }

What's cool about this is that you can use it at any level in your SCSS. For instance, you can either group a set of rules like so:

@include respond-to(phone) {
    body { background: red; }
    input { width: 100%; }

or, you can use it in the middle of an already deeply nested SCSS structure, such as:

body {
    input {
        background: white;

        @include respond-to(phone) {
            background: blue;

A new Dockbar display mode

One of the things you may have noticed about the Classic theme in 6.2 is that the Dockbar doesn't appear to be a bar, exactly. If you're not sure what I mean, here is what it looks like in 6.2:


It may not be obvious, but in this mode, the dockbar is actually split, as you can see here:


One of the things we wanted to do was to find a way to make the dockbar appear a little less intrusive to the overall design. We also wanted this to be something that all themes could use if they wanted to.

So what we did was add a new mode for the Dockbar. Basically, if you add a CSS class onto your body element called dockbar-split, it will trigger the new display mode.

In order to add this CSS class, you don't even need to overwrite your portal_normal template. Simply create a file _diffs/templates/init_custom.vm and in there add this code:

#set ($css_class = "${css_class} dockbar-split")

We also made it so that the deafult style was much more neutral. While the Classic theme looks like the above screenshots, this is what the Dockbar looks like in a default theme with no customizations:


And here's what the Split Dockbar looks like with no customizations:


As you can see, it's much less targeted to any one specific design.

We are bundling in FontAwesome by default

If you haven't heard of FontAwesome, you should definitely check it out. It offers a wide range of icons and a lot of flexibility.

But the main benefits can be summed up as:

  • Completely scaleable icons, even for high resolution devices
  • Easily change the size and the color of the icons via CSS

Final words

Overall, we've addressed a lot of the issues we've seen theme developers run into, as well as add features that solve many of their common business goals.

As always, feel free to ask any questions you may have here, or in the forums :)

Hi Nate,
this is a great sum-up of the upcoming changes. But I think there is a little typo ;).
/* will only style tablet and desktop displays greater than 768px */
@include respond-to(phone, tablet) {
Shouldn't it be respond-to(dektop,tablet)?
Hey Nate, awesome post! I think some of this will need to find its way into the dev docs (esp. the part about needing an aui.css - unless I missed it).

One other thing - I think one of your code snippets left off "$FontAwesomePath: "aui/alloy-font-awesome/font" !default;" as the first line.
Good summary of the why bootstrap 2.3.2. I can completely agree with not inserting bootstrap 3.0 in the later stage of the development cycle. I am not sure that I agree with the IE 7 issue. With IE 7 now at less than 1% use world wide (according to multiple browser tracking sites), this does not seem to be a reasonable course of action. Our company development efforts, as far as browser support is concerned, now simply looks to have stated support for the current version and one back. This is pretty hard to do now with the rapid release cycles of Firefox and Chrome, but it does provide a message to our customer base that the current browsers are going to provide them the best web experience.

So, if someone wants to replace to Bootstrap 3, in their environment, should they go ahead now, or wait for an update to 6.2 that could include it?
Hi Cordell,
Thanks for your response.
About IE7, I have a few thoughts on that part.
First, I am genuinely happy for you that you are able to limit support down to the current and latest browser. I think progressive (more timid souls may even say aggressive) support policies like that really help push the web forward.
That being said, there were a couple of factors that push us towards still including it as part of limited support is that while IE7 support is less than 1% amongst the general population, there are still many enterprise deployments that are relying on it.

It's simple enough to tell individual users "Upgrade your browser", but when an IT department is looking at upgrading hundreds of thousands of users, retraining those users for a new browser, etc, it's not as simple as just making them upgrade.

The situation is even more problematic in the Asian markets, where IE 6 & 7 usage in enterprises is still pretty strong.

So for us, we're always trying to find that balance of moving the web forward and still helping IT departments (and the people in them and at their mercy) accomplish their business goals.

Now, to your question, we can't just push out Bootstrap 3 as an update to Liferay 6.2. Changing a core piece of infrastructure on users as part of an update like that is an easy way to make a lot of normally nice folks really angry emoticon

The upgrade to Bootstrap 3 is relatively simple, there are still a lot of places throughout the portal that rely on the old css classes and markup.
For instance, if you look at You'll see there are multiple pieces that were changed and any third-party app may rely on those patterns still being there.

What we're hoping to do is to release a hook in the marketplace that upgrades the default theme as well as all of the pieces throughout the portal to reflect the changes in Bootstrap 3.

We're still working through the details on this hook but we'll let everyone know when it becomes available.

You could attempt to do it yourself, but beware all of the pieces (including the taglibs) that rely on the Bootstrap 2 way of doing things (specifically the layout classes, that would be a big one).

Thanks again for your comment Cordell emoticon
Hey Nate, beyond the hook are we planning to upgrade to Bootstrap 3 in which version of Liferay? 7.0?
Yeah, that seems to be the plan. It will be at least 3.0, but depending on what's released from Bootstrap till the release, and when the 7.0 release is, we'll try to aim for the latest stable branch.
Hi Nate & Others,

Liferay product and the entire team - is awesome. I have successfully set Bootstrap 3 based theme purchased from bootstrapwrap. Check it out -
Salam Muhammad Shakir,

Have you integrated Bootstrap 3 with Liferay 6.2 or 6.1?

Apologies for delayed reply. It is on 6.2
Hi its perfectly working in IE8 . but my problem is when i override the bootstrap class at particular device its not working in IE8. For example <div class="span4 services"></div>css file:@media(min-width:1024px){.services{width:33.3% !important;}}. its well working in chrome but not in IE8.i added htmlshiv.js and respond.js and brosercompatibility.js.but there is no use. please give me suggestion. thanks
Thanks for this post. Very helpful. However, I'm still not sure how I can use Bootstrap 3 with LR 6.2. Can you please revisit that section or may be throw some light on which section of this article actually speaks about it? Sorry about this, I'm just totally confused with all these new changes in LR.
Thanks in advance.
Thanks for writing this. However, I'm a little confused with regard to your instruction on how to migrate a vanilla bootstrap 2.3.2 theme into Liferay.
You said to create an aui.css file. Do you mean create, as in create an empty file or do you mean copy? And if you mean copy then which file should be copied to aui.css? How does the css in the theme's bootstrap.css file get folded in? A little more discussion about this would be greatly appreciated.
Hi Joseph, sorry if that wasn't 100% clear. But basically, what you would do is take your bootstrap.css or whatever theme css file you received and name that aui.css and place it in your _diffs/css directory.
The portal looks in every theme's css directory for an aui.css and uses that as it's bootstrap file.
Does that help at all?
Yes it does. Thanks. Actually, with nothing better to do I tried that and it sort of worked. The primary navigation seems to use different CSS classes than what's used in Liferay, but I'm sure it can get massaged into working. Thanks again.
Thanks, Nate, for this post!
I wondered if you be able to shed some light on your team's use of Sass and Compass in the building of the new responsive themes, and how one might go about leveraging those tools in a similar manner for custom theme development.
Any roadmap or advice on getting those tools set up for theme work would be of great benefit to anyone looking to build themes for 6.2.
I am inheriting the _styled theme for a custom theme of mine.
I was getting the dockbar in the old liferay 6.1 style. I then somehow managed to get the split dockbar by making css changes.
But now, I'm not getting the icons for the add, preview etc options.
Any idea what I need to do to get those icons?
Hi Nate,

Is it possible to use Twitter Bootstrap JS component inside Liferay?

Great job!

I have a theme with Bootstrap3 in Liferay 5.2. The alternatives I see to migrate to 6.2 are:
- Downgrade to Bootstrap 2.3
- Wait for Liferay 7
- Wait for the hook which is discussed above

is it still plans to develop the hook mentioned above?

Thanks and regards
I just tried following Nate's instructions on getting Font Awesome working with 6.2. The code he mentions needs to be inside "_diffs/css/aui.css", NOT "_diff/css/custom.css".
Couple helpful tips for people struggling to get Bootstrap going in Liferay 6.2 that weren't exactly clear to me as I started

If you're implementing a Bootswatch theme in Liferay 6.2, make sure it is version 2.3.2,

Next you have to follow the instructions from this separate topic thread which Nate left out completely.

That also means that you need to do some conversions with their included sass and less files using a regex tool. I used this free one online.

Basically you have to copy the bootswatch less into that tool above, copy the pattern
, and below the substitution is the output which you copy, re-add overwriting the prior change, so on and so forth down Jauns table of changes for both files, following his directions.

I mean, this whole topic is a mess, its extremely confusing. I met Nate at the Liferay Symposium in Boston. Nice guy and I'm sure he's busy but they need to prioritize documentation. There is nothing remotely useful on the Liferay Developer Network yet on implementing Bootstrap in 6.2. Hopefully that changes.

I'm happy to answer questions to anyone still having problems. ( I'm not paid by Liferay )
Hi Sean,
Thanks for posting your comment, as well as helping others out.
Sorry I didn't include the link to the other blog post (though to be fair, it was posted 6 months after mine emoticon.
Regarding converting the less to sass, one of the guys here wrote this: which may help a bit.

Thanks again for the comment, and it was great meeting you in Boston emoticon

Thanks for the replies guys. I see the alternatives. Still makes me sad to have a real theme in an earlier version of Liferay with Bootstrap 3 and having to downgrade: ___ (

Thanks again and best regards
Hi! I work like a front-end Developer on Liferay, thank for this blog post.
But, I don't see the benefit of your section "Why do all of the Bootstrap rules have .aui in front of them?".

1 - If you put the .aui class only on a specific node (like you say, on a portlet), all your administration lost the benefit of bootstrap (no bootstrap style on the admin panel for adding content, on the pop ups). We can't put .aui on an other node.

2 - CSS is cascading style sheet, if you are this selector ".aui .btn", he have an bigger priority than this selector ".btn" even if you declare this after. All the styles on aui.css are too strong. All theme style has to be stronger, and it's not really interesting

We built 4 differents websites with this system, this year, and and this "feature" has caused us problems.

What we badly understood?