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(phone, tablet) {
    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 :)

Write a blog post too!

Write a deep dive into how you use Liferay projects in your technology stack. Or let people know useful tips and tricks for a particular functionality. The Liferay community needs you!

Login or Create an account