Anatomy of a Theme

Custom themes are based on differences from one of several built-in Liferay themes.

The structure of a theme is designed to separate different types of resources into easily accessible folders. The full structure of the deep blue theme is shown below:

/deep-blue-theme/
    /docroot/
        /WEB-INF/
            liferay-plugin-package.properties
        /_diffs/ (subfolders not created by default)
            /css/
            /images/
            /js/
            /templates/
        /css/
            application.css
            base.css
            custom.css
            dockbar.css
            extras.css
            forms.css
            layout.css
            main.css
            navigation.css
            portlet.css
        /images/
            (many directories)
        /js/
            main.js
        /templates/
            init_custom.vm
            navigation.vm
            portal_normal.vm
            portal_pop_up.vm

            portlet.vm

You will notice that there is a _diffs folder inside the docroot directory of your theme; this is where you will place your theme code. You only need to customize the parts of your theme that will differ from the parent theme. To do this, you mirror the directory structure of the parent theme inside of the _diffs folder, placing only the folders and files you need to customize there.

You will also notice that there are several other folders inside docroot; these were copied over from the parent theme in your Liferay bundle when you deployed your theme. You should use these files as the basis for your modifications. For example, to customize the navigation, you would copy navigation.vm from deep-blue-theme/docroot/templates/navigation.vm into deep-blue-theme/docroot/_diffs/templates folder (you may have to create this folder first). You can then open this file and customize it to your liking.

For custom styles, create a folder named css inside your _diffs folder and place a single file there called custom.css. This is where you would put all of your new styles and all of your overrides of the styles in the parent theme. Custom.css is loaded last, and so styles in this file are able to override any styles in the parent theme.

Best practice recommends that you make all your custom themes using only the custom.css file, and that you not override any of the templates unless absolutely necessary. This will make future upgrades far easier, as you won't have to manually modify your templates to add support for new Liferay features.

Whenever you make modifications to your theme, redeploy it by opening a terminal in themes/deep-blue-theme and entering the command ant deploy. Wait a few seconds until the theme deploys, and then refresh your browser to see your changes.

Tip: If you wish to see changes even more quickly, it is also possible to modify you theme directly in your Liferay bundle. In our example, custom.css is located in liferay-portal-[version]/tomcat-6.0.26/webapps/deep-blue-theme/css. However, for modifications made here to appear in your browser as soon as you refresh the page, you must enable Liferay Developer Mode. See the Liferay wiki for more information.

Also make sure that you copy any changes you make back into your _diffs folder, or they will be overwritten when you redeploy your theme.