Advanced Theme in Liferay User Interface Development

Liferay User Interface Development

Develop a powerful and rich user interface with Liferay Portal 6.0

• Design usable and great-looking user interfaces for Liferay portals
• Get familiar with major theme development tools to help you create a striking new look for your Liferay portal
• Learn the techniques and tools to help you improve the look and feel of any Liferay portal
• A practical guide with lots of sample code included from real Liferay Portal Projects free for use for developing your own projects

Changing theme.parent property in theme

Liferay provides four different theme implementations out-of-box in the ${PORTAL_ROOT_HOME}/html/themes/ folder as shown in the following screenshot:

When you create a new theme in the themes/ directory of the Plugins SDK, the Ant script will copy some files to the new theme from one of these three folders, _styled/, _unstyled/, and classic/, which can be specified in the ${PLUGINS_SDK_HOME}/themes/build-common-theme.xml file.

For example, you can go to the ${PLUGINS_SDK_HOME}/themes/ directory and run create.bat palmtree “Palm-Tree Publications theme” on Windows or ./create.sh palmtree “Palm-Tree Publications theme” on Linux, respectively. Or you can use Liferay IDE to create same New Liferay Theme Plugin Project. This will create a theme folder named palmtree-theme in the Liferay Plugins SDK environment. When you run ant to build and deploy the theme and then apply the newly created theme to your page, you will find out that the look and feel of the page is messed up, as shown in the following screenshot:

If you are familiar with theme development in Liferay Portal 5.2, you may wonder what has happened to the theme created in Liferay Portal 6 Plugins SDK because you would expect a fully working theme with two simple commands, create and ant. This is because the following build.xml file in your theme specifies _styled as the value for the theme.parent property:

<?xml version=”1.0″?>
<project name=”palmtree-theme” basedir=”.” default=”deploy”>
<import file=”../build-common-theme.xml” />
<property name=”theme.parent” value=”_styled” />
</project>

This means that when your newly created theme is built, it will copy all the files from the _styled/ folder in the ${PORTAL_ROOT_HOME}/html/themes/ directory to the docroot/ folder of your theme. The default _styled/ folder does not have enough files to create a completely working theme and that is why you see a messed-up page when the theme is applied to a page. The reason why this default _styled/ folder does not include enough files is that some Liferay users prefer to have minimal set of files to start with.

You can modify the build.xml file for your theme in the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/ folder by changing value of the theme.parent property from _styled to classic, if you prefer to use the Classic theme as the basis for your theme modification.

<property name=”theme.parent” value=”classic” />

Now you will see that your page looks exactly the same as that with the Classic theme after you build and apply your theme to the page (refer to the following screenshot):

Adding color schemes to a theme

When you create a theme in the Plugins SDK environment, the newly created theme by default supports one implementation and does not automatically have color schemes as variations of the theme. This fits well if you would like to have a consistent look and feel, especially in terms of the color display, across all the pages that the theme is applied to.

In your portal application, you might have different sites with slightly different look and feel for different groups of users such as physicians and patients. You might also need to display different pages such as public pages with one set of colors and the private pages with a different set of colors. However, you don’t want to create several different themes for reasons such as easy maintenance. In this case, you might consider creating different color schemes in your theme.

Color schemes are specified using a Cascading Style Sheets (CSS) class name, with which you are able to not only change the colors, but also choose different background images, border colors, and so on.

In the previous section, we created a PalmTree Publication theme, which takes the Classic theme as its parent theme. Now we can follow the mentioned steps to add color schemes to this theme:

1. Copy the ${PORTAL_ROOT_HOME}/webapps/palmtree-theme/WEB-INF/liferay-look-and-feel.xml file to the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/WEB-INF/ folder.
2. Open the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/WEB-INF/liferay-look-and-feel.xml file in your text editor.
3. Change <theme id=”palmtree” name=”PalmTree Publication Theme” /> as shown in the highlighted lines here, and save the change:

   <look-and-feel>
   <compatibility>
   <version>6.0.5+</version>
   </compatibility>
   <theme id=”palmtree” name=”Palm Tree Publications Theme”>
   <color-scheme id=”01″ name=”Blue”>
   <css-class>blue</css-class>
   <color-scheme-images-path>${images-path}/color_schemes/
   blue</color-scheme-images-path>
   </color-scheme>
   <color-scheme id=”02″ name=”Green”>
   <css-class>green</css-class>
   </color-scheme>
   <color-scheme id=”03″ name=”Orange”>
   <css-class>orange</css-class>
   </color-scheme>
   </theme>
   </look-and-feel>

4. Go to the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/palmtree-theme/_diffs/ folder and create a css/ subfolder.
5. Copy both custom.css and custom_common.css from the ${PORTAL_ROOT_HOME}/html/themes/classic/_diffs/css/ folder to the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/css/ folder. This is to let the default styling handle the first color scheme blue.
6. Create a color_schemes/ folder under the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/palmtree-theme/_diffs/css/ folder.
7. Place one .css file for each of your additional color schemes. In this case, we are going to create two additional color schemes: green and orange.
8. To make the explanation simpler, copy both the green.css and orange.css files from the ${PORTAL_ROOT_HOME}/html/themes/classic/_diffs/css/color_schemes/ folder to the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/css/color_schemes/ folder.
9. Copy all images from the ${PORTAL_ROOT_HOME}/html/themes/classic/_diffs/images/ folder to the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/images/ folder.
10. Add the following lines in your ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/css/custom.css file:

    @import url(color_schemes/green.css);
    @import url(color_schemes/orange.css);

    If you open either the green.css or the orange.css file, you will be able to identify the styling for the CSS by using a color prefix for each CSS definition. For example, in the orange.css file you would find that each item is defined like this:

    orange .dockbar {
    background-color: #AFA798;
    background-image: url(../../images/color_schemes/orange/dockbar
    /dockbar_bg.png);
    }
    .orange .dockbar .menu-button-active {
    background-color: #DBAC5C;
    background-image: url(../../images/color_schemes/orange/dockbar
    /button_active_bg.png);
    }

    In the green.css file, the style is defined like this:

    green .dockbar {
    background-color: #A2AF98;
    background-image: url(../../images/color_schemes/green/dockbar/
    dockbar_bg.png);
    }
    .green .dockbar .menu-button-active {
    background-color: #95DB5C;
    background-image: url(../../images/color_schemes/green/dockbar/
    button_active_bg.png);
    }

    Also, notice that the related images used for the different color schemes are included in the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/images/color_schemes/ folder.

11. Re-build and deploy the PalmTree Publication theme.
12. Log in as administrator and go to the Control Panel to apply this theme to the PalmTree Publications Inc. organization. You will be able to see three color schemes available under this theme.
13. Select any of them to apply it to the Public Pages.
14. Take a screenshot of the page when each of the color schemes is applied and save it as thumbnail.png in the corresponding blue, green, and orange subfolders in the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/images/color_scheme/ folder. Three screenshots are used to distinguish between the three color schemes in the Control Panel as seen in the following screenshot:

The following screenshots shows how each of the three color schemes looks when applied to a portal page:

As shown in above screenshot, color scheme blue has been applied on the Home page, by default. The following screenshot shows applying color scheme green on the current page. Of course, you would be able to apply color schemes blue or green in the entire site, if required.

Similar to color schemes blue and green, you can apply color scheme orange as well on the current page or the entire site, as shown in following screenshot:

So it works! The page background is with a hue of gray color. Now, what if we want to change the page background color to red for the green color schema?

Update the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/css/color_schemes/green.css file as follows. The commented outline is the original content. The next line after the comment is the new content. The #FF0000 code is for the red color.

body.green, .green .portlet {
/*background-color: #F1F3EF;*/
background-color: #FF0000;
}

Re-deploy the PalmTree theme and refresh the portal page that uses the green color scheme. Now, you should be able to see the portal page with a red background color.

As you can see, you can use theme color schemes to create some variants of the same theme without creating multiple themes. This is useful when you have different but related user roles such as physicians, nurses, and patients and you need to build a different site for each of them. You can use the color schemes to display each of these sites in a slightly different look and feel.

Configurable theme settings

There are many use cases where you would like to change some default settings in the theme so that you can modify the values after the theme is built and deployed. Fortunately, each theme can define a set of settings to make this configurable. The settings are defined as key-value pairs in the liferay-look-and-feel.xml file of the theme with the following syntax:

<settings>
<setting key=”my-setting1″ value=”my-value1″ />
<setting key=”my-setting2″ value=”my-value2″ />
</settings>

These settings can then be accessed in the theme templates using the following code:

$theme.getSetting(“my-setting1”)
$theme.getSetting(“my-setting2”)

For example, I need to create two themes—PalmTree Publications theme and AppleTree Publications theme. They are exactly the same except for some differences in the footer content that includes copyright, terms of use, privacy policy, and so on. Instead of creating two themes packaged as separate .war files, we create one set of two themes that share the majority of the code including CSS, JavaScript, images, and most templates; but with one configurable setting and two different implementations of the footer Velocity files.

Here is how this can be done:

1. Open ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/WEB-INF/liferay-look-and-feel.xml in the above sample PalmTree theme.
2. Copy the PalmTree theme section and paste it in the same file but after this section.
3. Rename the values of id and name from palmtree and PalmTree Publications theme to appletree and AppleTree Publications theme in the second section.
4. Add the following setting to the palmtree section before the color-scheme definition:

   <settings>
   <setting key=”theme-id” value=”palmtree” />
   </settings>

5. Add the following setting to the appletree section before the color-scheme definition:

   <settings>
   <setting key=”theme-id” value=”appletree” />
   </settings>

6. Find the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/WEB-INF/liferay-look-and-feel.xml file as follows:

   <look-and-feel>
   // ignore details
   <theme id=”palmtree” name=”PalmTree Publications Theme”>
   <settings>
   <setting key=”theme-id” value=”palmtree” />
   </settings>
   <color-scheme id=”01″ name=”Blue”>
   // ignore details
   </color-scheme>
   </theme>
   <theme id=”appletree” name=”AppleTree Publications Theme”>
   <settings>
   <setting key=”theme-id” value=”appletree” />
   </settings>
   <color-scheme id=”01″ name=”Blue”>
   // ignore details
   </color-scheme>
   </theme>
   </look-and-feel>

7. Copy the portal_normal.vm file of the Classic theme from the ${PORTAL_ROOT_HOME}/html/themes/classic/_diffs/templates/ folder to the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/templates/ folder.
8. Open the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/templates/portal_normal.vm file
9. Replace the default footer section with the following code:

   #set ($theme_id = $theme.getSetting(“theme-id”))
   #if ($theme_id == “palmtree”)
   #parse (“$full_templates_path/footer_palmtree.vm”)
   #else
   #parse (“$full_templates_path/footer_appletree.vm”)
   #end

10. Create your own version of the two footer Velocity templates in the ${PLUGINS_SDK_HOME}/themes/palmtree-theme/docroot/_diffs/templates/ folder.
11. Add related CSS definitions for your footer in your custom.css file.
12. Build and deploy the theme .war file.

Now you should be able to see both the PalmTree and AppleTree themes when you go to the Control Panel to apply either theme to your page.

Based on the theme to be used, you should also notice that your footer is different.

Of course, we can take other approaches to implement a different footer in the theme. For example, you can dynamically get the organization or community name and render the footer differently. However, the approach we explained previously can be expanded to control the UI of the other theme components such as the header, navigation, and portlets.

Portal predefined settings in theme

In the previous section, we discussed that theme engineers can add configurable custom settings in the liferay-look-and-feel.xml file of a theme. Liferay portal can also include some predefined out-of-the-box settings such as portlet-setup-show-borders-default and bullet-style-options in a theme to control certain default behavior of the theme.

Let us use portlet-setup-show-borders-default as an example to explain how Liferay portal controls the display of the portlet border at different levels.

If this predefined setting is set to false in your theme, Liferay portal will turn off the borders for all portlets on all pages where this theme is applied to.

<settings>
<setting key=”portlet-setup-show-borders-default” value=”false” />
</settings>

By default, the value is set to true, which means that all portlets will display the portlet border by default.

If the predefined portlet-setup-show-borders-default setting is set to true, it can be overwritten for individual portlets using the liferay-portlet.xml file of a portlet as follows:

<liferay-portlet-app>
// ignore details
<portlet>
<portlet-name>sample</portlet-name>
<icon>/icon.png</icon>
<use-default-template>false</use-default-template>
<instanceable>true</instanceable>
<header-portlet-css>/css/main.css</header-portlet-css>
<footer-portlet-javascript>/js/main.js</footer-portlet-javascript>
<css-class-wrapper>sample-portlet</css-class-wrapper>
</portlet>
// ignore details
</liferay-portlet-app>

Set the use-default-template value to true if the portlet uses the default template to decorate and wrap content. Setting it to false will allow the developer to maintain the entire output content of the portlet. The default value is true. The most common use of this is when you want the portlet to look different from the other portlets or if you want the portlet not to have borders around the output content.

The use-default-template setting of each portlet, after being set to either true or false, in the liferay-portlet.xml file, can be further overwritten by the portlet’s popup CSS setting. Users with the appropriate permissions can change it by going to the Look and Feel | Portlet Configuration | Show Borders checkbox of the portlet, as shown in the next screenshot:

Embedding non-instanceable portlets in theme

One common requirement in theme development is to add some portlets in different components of a theme.

For example, you might want to add the Sign In portlet in the header of your theme, the Web Content Search portlet in the navigation area, and the Site Map portlet in the footer area. All the Liferay out-of-the-box portlets can be referred in the ${PORTAL_ROOT_HOME}/WEB-INF/liferay-portlet.xml file.

How can this be achieved?

Well, it can be quite easy or pretty tricky to embed an out-of-the-box portlet in a theme.

Embedding Dockbar and Breadcrumb portlets in a theme

The Dockbar portlet is embedded at the very top in the default Classic theme in the portal_normal.vm file as shown next:

#if($is_signed_in)
#dockbar()
#end

In the same way, the Breadcrumb portlet can be embedded in the content area of the Classic theme in the portal_normal.vm file:

#breadcrumbs()

Embedding Language and Web Content Search portlets in a theme

Some other Liferay out-of-the-box portlets such as the Language and Web Content Search portlets can be embedded in a theme or a layout template easily.

For example, the Web Content Search portlet can be added to the far right side of the horizontal navigation area of your theme as follows in the navigation.vm file of your theme.

<div id=”navbar”>
<div id=”navigation” class=”sort-pages modify-pages”>
<div id=”custom”>
$theme.journalContentSearch()
</div>
// ignore details
</div>
</div>

In the same way, the Language portlet can be embedded in the portal_normal.vm Velocity template file of your theme:

$theme.language()

Again, you need to add the necessary CSS definitions in your custom.css file to control the look and feel and the location of your embedded portlet(s).

Embedding Sign In portlet in the header area of a theme

Sometimes the theme design requires that the Liferay Sign In portlet be in the header area. By default, the Sign In portlet has a portlet border but we need to disable it. The previously mentioned approaches for embedding a portlet in a theme through Velocity attributes in a template do not work in this case because we need to customize the default UI of the embedded portlet.

Instead, we can add the following code to the header section in the portal_normal.vm file in our sample PalmTree theme:

#if(!$is_signed_in)
#set ($locPortletId = “58”)
$velocityPortletPreferences.setValue(“portlet-setup-show-borders”,
“false”)
#set($locRenderedPortletContent = $theme.runtime($locPortletId, “”,
$velocityPortletPreferences.toString()))
$locRenderedPortletContent
$velocityPortletPreferences.reset()
#end

After the theme is re-built and re-deployed, we can see that the Sign In portlet is rendered in the header area underneath the logo without the portlet border.

The next step for us is to modify the custom.css file and the related files by adding CSS definition to control the location and look and feel of this Sign In portlet. The following screenshot shows the Sign In portlet in the header area and the Web Content Search portlet in the navigation area in a working theme in the production environment: