Using existing Bootstrap themes in Liferay (Part I).

Yes, it's true bootstrap give us a lot of improvements for creating themes. And is also true that since Liferay 6.2 we can take advantage of all this useful tools for developing your own themes in Liferay.

Looking for developing my own themes for some personal portals (yes, I like developing in Liferay in my free time too laugh) without being a frontend developer seemed more less complicated. Although there were some attempts for explaining it, the steps were not clear enough for a bootstrap newbie like me.

After some investigation (and with the help from Nate Cavanaugh, Ilyan Peychev and Chema Balsas, thanks very much mates!) I could finally put all pieces together and create some steps for integrating an existing bootstrap theme into Liferay sucessfully.

So after reading this 2-part blog series you would be able to get any already developed bootstrap theme and use it in Liferay. In fact, I used some of the existing bootstrap themes showcases and generators.

As what I've seen round there, there are two types of themes from bootstrap showcases/generators:

  1. Themes with downloadable LESS files.
  2. Themes with complete bootstrap (v. 2.3.2) CSS.

In this post I'll be explaining the steps for the first point. So here we go!

Themes from LESS files (http://bootswatch.com/2/)

When searching for bootstrap themes, you probably found bootswatch as one of the first results. It has some free themes and many themes for purchasing. As you can see just after opening the page, you are selecting Bootstrap v.2. This is required for Liferay 6.2, as it uses Bootstrap 2.3.2. But there are good news. Next Liferay version will be compatible with Bootstrap v3, although you have to stay with v.2.3.2 until new version is out.

Just choose one of your free or purchased theme, and download the variables.less and bootswatch.less files (in my case, I've chosen "Slate" free theme):

After downloading those files, follow these steps:

  1. Create theme using Liferay IDE or SDK command line  (styled + Velocity, if using Freemarker you will find this known error: https://issues.liferay.com/browse/LPS-47408).
  2. Create these new files, using _diffs directory as usual:
    1. _diffs/css/_aui_variables.scss
    2. _diffs/css/_aui_custom.scss
  3. Copy content from variables.less into _diffs/css/_aui_variables.scss
  4. Copy content from  bootswatch.less into _diffs/css/_aui_custom.scss
  5. Downloaded files are in LESS format. We need to convert them to SASS. There are some rules we can follow easily:
    • replace @ with $
    • replace . with @include for mixins
    • replace spin with adjust-hue
    • add !default to variable definitions
    • replace #gradient > .vertical with @include gradient-vertical
    • replace #grid > .style with @include grid-style
    • use grid-core and grid-fluid mixins instead of #grid > .core and #grid > .fluid
    • use font-shorthand instead of #font > .shorthand
    • replace fadein with fade-in
    • move @import for reset below mixins, because it uses tab-focus mixin in bootstrap.scss
    • move @import for reset below mixins, because it uses tab-focus mixin in bootstrap.scss
    • pass grid-* mixin arguments to generators, because otherwise the generator mixins will use the default variables pull transition definition into variable
  6. Below I'll write the replacement rules I've followed, using regex patterns and the replacement value. LESS replacements:
    Pattern/string to replace Replacement
    @(?!(?:import|media|charset|font-|page|((-(moz|o|ms|webkit)-)?(keyframes|viewport)))) $
    spin\( adjust-hue(
    \.([\w-]+)(?=\() @include $1
    #gradient > @include vertical @include gradient-vertical
    #gradient > @include directional @include gradient-directional
    &- Replace with the css class where that element belongs to: (ex.:  &-inverse belongs to .navbar, so it should be .navbar-inverse)
  7. Change icon path in _aui_variables.scss:
$iconSpritePath:       "../images/aui/glyphicons-halflings.png";

$iconWhiteSpritePath:  "../images/aui/glyphicons-halflings-white.png";

 

Then, after executing "ant deploy" (or using Liferay IDE) your theme should deploy properly and result, if you chose the same theme as me, should be like following:

 

 

Looks good, isn't it? As you can see, you can have a bootstrap theme as a Liferay theme in only few minutes!

That's all for now! In next blog post I'll be showing how to generate a custom bootstrap theme from scratch using some of the available generators existing in Internet, and use it as a Liferay theme.

Hope you liked it, stay tuned! wink

Blogues
Great job, Juan! Btw, these steps above look for me as good candidates to be automatized with some tool (hint, hint).
Great article. Waiting for next article with some example for developing bootstrap theme from scratch.
How can I perform "Themes from LESS files" with a maven based project ?
In a maven project there is no _diffs folder, putting the files _aui_custom.scss and _aui_variables.scss in the webapp/css folder does not work (something happens to the layout but not the above mentioned result occurs)

Thanks in advance
I still can't make it work, even I think that's a very useful tutorial. The created tthem (following the steps) provides a theme without style.

I think I'm missing something very basic, could you please upload the theme explained in this tuto in order to check the source code of the result?
Hi JL,

What do you mean by "without style"?
Not style at all, like if no css was working in the html.
Seems that your theme css is wrong, and after "ant deploy" it failed building the css. Try to make any change and execute "ant deploy" again and see if there is any error in logs (Liferay IDE console)
It did not fail on the console.

The steps are the described on the tutorial.
1.- Create the theme through console.
2.- Add the less files to the _diffs , changing their name and replacing the elements.
3.- Compile and deploy.

No build or deploy error but the page appears without stlyle.

I think that the problem might be in the LESS-SASS replacements or something like that, that's why I´d like to see the final source code of the theme in order to check by myself what I am doing wrong.

Many thanks, Juan
Hi JL,
sorry, I prefer you to implement theme successfully, so if there is any error in steps I can update the blog post :-).
Please, create a new theme from scratch, but this time use Liferay IDE, and follow the same steps.
Well, I did it again with no luck. I tried with 2 different bootstrat themes from the url you provided.

One thing that I have noticed is that I think that there are more changes than the ones you said: Not only the '&-' must be changed (changing the ampersand with the element it belongs to) but with the &. elements too (changing them with the elements they belong to).

In any case I did it again with no luck. I would like to contact you with a more complete list of steps done in order to see what might happen.
The css should be fine if you didn't see any error while building the theme. In that phase the SASS files are compiled, and there would be errors there if you didn't replace something properly.
BTW, did you try with "Slate" theme and followed all the steps?
It finally works. The key was that I am newbie at bootstrap (being generous) and I didn't know that it had any kind of compilation. The deploy was succesfull and I did'nt look at the log trace. There was an error in the middle.

Using the regex you provided for spin\( ---> adjust-hue( it did not work properly for me. The final result was adjust-hue$btnPrimaryBackground instead of adjust-hue($btnPrimaryBackground

On the other hand, all the &- and the &. must be replaced (not only the &- ).

Many thanks for the support and for the blog entry, this makes a vey easy way to provide a brand new look to a portal.
Glad it worked.
Are you sure the adjust-hue($btnPrimaryBackground doesn't work? It should.
Thanks for the other tip. I will check it and update the blog entry.
It doesn't work. I tested it twice. It does not add the final '(' like on adjust-hue$btnPrimaryBackground instead of adjust-hue($btnPrimaryBackground

I´m using Notepad++
Well, maybe I didn't explained clearly in the blog post, but as you can see in replacement table header: Pattern/string to replace.

In this case, it's a pattern, so you can use some regexp tool for finding that pattern. If not, you can do it "manually". The final result should be replacing all "spin(" with "adjust-hue(", and same with other functions that doesn't exist in SASS.
Hey, can you send me your scss files. I think I am getting similar errors, however, even after rectifying them, my theme doesn't look good.
If you intend to use font awesome, Nates suggestion to add his code to custom.css is incorrect. It actually needs to be inside aui.css.

Also, once you get font awesome going, I found this website has the correct class names for usage inside liferay.
http://nickpiesco.github.io/alloy-ui-font-awesome-cheatsheet/
I didn't find #gradient > @include vertical.
I found:
#gradient > .vertical-three-colors(...)
and
#gradient > .directional(...)
Do I need to replace it? With what strings? :
@include gradient-vertical OR .gradient-vertical...
and
@include gradient-directional OR . gradient-directional
Thank you for the article!

I am thinking about custom hooks: Liferay 6.2 AUI compatibility with Bootstrap 2.3.2 is nothing more that usage of standard CSS classes from Bootstrap v.2.3.2 - so that probably we may have new JSP versions compatible with version 3.3.1

I am going to try that... nothing more than replacing some CSS class names with Bootstrap 3.3.1 compatible names.
For those who wants real hack (such as Bootstrap 4 on Liferay 7) check this:
https://github.com/liferay/alloy-ui/wiki/Liferay-Integration
And especially this:
https://github.com/liferay/alloy-ui/wiki/Bootstrap-3:-Migration-Guide

Indeed, it is Alloy UI classes, powered by Bootstrap.
Hello Juan.

I'm struggling against converting files, and when I compile with 'deploy' i get no error, and the theme applied to page is completely unstyled in the end.

Can you post those two converted files ? It could be a great help to understand what I am doing wrong.
It could be even better to post the entire war theme obtained , so we can check everything is going fine in this workflow.

Many Thanks.
Actually I solved the issues I had. The problem is indeed in the LiferayIDE.

deploy will run the task build-css. The first time you do it this task will bring to output any errors in your scss files. But if you modify the scss files, those are no more considered from build-css and it returns without errors.

So, for me the solution was to 'clean' before 'deploy' every time. I never experiences this with css only themes.
[...] This is the second (and last) part of my blog series for using existing Bootstrap themes into Liferay 6.2. In my previous blog post I talked about using LESS files, and how to, by simply changing... [...] Read More
[...] This is the second (and last) part of my blog series for using existing Bootstrap themes into Liferay 6.2. In my previous blog post I talked about using LESS files, and how to, by simply changing... [...] Read More
[...] Calvin Quintero: IIs there any way to use existing Bootstrap themes in Liferay? Yes, please take a look at these blog posts:... [...] Read More
The link https://github.com/m5o/sass-bootstrap/blob/master/README.md#sass-conversion-quick-tips is not available.
The link https://github.com/m5o/sass-bootstrap/blob/master/README.md#sass-conversion-quick-tips is not available.
Thanks Quang. I've replaced that link with the tips text, as this part is a bit old and this way we will keep the information forever visible.