Recently I have had the opprotunity to upgrade some client themes from 6.1 to 6.2. The purpose of this post is to help you avoid some issues that I ran into during the process.
- Responsive out of the box
- Uses Twitter bootstrap 2.3.2
- Uses Alloy UI 2.0
- SASS (been around since 6.1 but still great)
- mixing (respond-to)
TB (Twitter Bootrap)
Liferay 6.1 doesn't come responsive out of the box. With many upgrade projects, the client's theme for Liferay 6.1 also included TB 3.0, since TB 3.0 was the latest and greatest version. The issue arises in Liferay 6.2 where the core product uses TB 2.3.2 without the bootstrap JS.
I started down the path of trying to include the TB 3 with Liferay 6.2. It didn't go well. Alot of conflicts occured. So my final strategy was to upgrade their theme using TB 2.3.2 markup. Then when needed memick some styles from TB 3.0 when needed.
Documentation is a little tricky when it comes to working with Liferay's Version of Twitter Bootstrap 2.3.2 contained in Liferay 6.2. When Liferay 6.2 was built, Liferay didn't want to include JQuery library in their product, so they striped out the TB JS and replaced some of the components with AlloyUI versions. First place to check is the offical twitter bootstrap 2.3.2 documentation http://getbootstrap.com/2.3.2/, this will be the place to look up html markup and css style class names. AlloyUI documentation can be found here http://alloyui.com/versions/2.0.x/
Every Theme can be different but overtime you learn what can work. When learning about the new version of liferay there are a couple of files that help me know what's avaliable to work with.
init.vm this file is located in your liferay bundle /webapps/ROOT/html/themes/_unstyled/templates/init.vm portal_normal.vm this file is located in your liferay bundle /webapps/ROOT/html/themes/_unstyled/templates/portal_normal.vm
Compare both of these files and notice any differences between 6.1 and 6.2 Once you have some of the book knowlege behind you let's start to upgrade the theme.
I recommend building a new theme and only pulling over what is necessary. Try to understand how all of the pieces of the theme work togeather (JS, CSS, Web Content, etc). Also by building a new theme using the latest plugins SDK will ensure that you are given the most up-to-date theme files to work with. From time to time files are added or removed from the theme build process.
In your new theme pull over the portal_normal.vm from the _unstyled folder. Then compare your old 6.1 portal_normal.vm. You have to play this balancing act of using the newer markup from 6.2 but also not change all of your classes and id's which will affect your css styles.
In the full run of the project, it is best to make the lease amount of changes to portal_normal, that way upgrading down the road will take less time. But realistly customizations will need to be made, but being organized will make your code easier for the next person. One way to be organized is to keep all variable customizations in init_custom.vm of the theme. This file is usally where I set variables to theme setting values, connect to services, or check user permissions. Then in the portal_normal.vm you have a simple boolean if statment to check if something needs to be displayed, based off of a variable from init_custom.vm
If you do need to change any of the class names for html elements, make note to update the css selectors later.
Best Practices
- css styles are located in custom.css file
- build theme using _styled parent theme (some may use classic, but classic contains alot of predefined styles that are not needed)
- init_custom.vm is where velocity variables are set and defined
- /js/javascript.js is where the theme's main javascript file is located.
- if you need to include js or css files, try to scope them to just the pages you need them. For example if you will only have a carousel on the home page wrap the includes with
<head>
#if($is_first_parent)
<link src />
<script />
#end
</head>-use respond-to() mixin
@import "mixins";
@include respond-to(phone, tablet){
body {
background-color: gray;
}
}