You can define settings to make your theme configurable for site administrators. You can add a simple text field input setting, which is the default setting type, or add other types of settings, such as text areas, checkboxes, etc. And you can even introduce logic in your settings to leverage different theme templates based on the settings selected by the user. In this tutorial, you’ll learn how to do all these things.
First, it’s best to learn how to add configurable settings to a theme.
Adding Configurable Settings to a Theme
Settings must be defined in the theme plugin’s
liferay-look-and-feel.xml file found in the
docroot/WEB-INF folder. The process is easier than you may think. Follow the steps below to get started.
If your project doesn’t have this file, create it in the
docroot/WEB-INFfolder and add the following XML content:
<?xml version="1.0"?> <!DOCTYPE look-and-feel PUBLIC "-//Liferay//DTD Look and Feel 6.2.0//EN" "http://www.liferay.com/dtd/liferay-look-and-feel_6_2_0.dtd"> <look-and-feel> <compatibility> <version>6.2.0+</version> </compatibility> <theme id="your-theme" name="Your Theme"> </theme> </look-and-feel>
nameattribute values with the ID and display name of your theme.
<settings></settings>tags between the theme’s
<setting/>element between the
<settings></settings>tags for as many settings as you want for the theme. For example, if you want to add a simple input field setting, you can add a setting like this one:
<setting key="your-key" value="your-value" />
If you stopped at this point, this setting would not be configurable for portal users. You’d have to manually change the setting in the theme plugin’s
liferay-look-and-feel.xmlfile and redeploy the plugin.
Note, that you can access your settings in your theme’s templates by calling
$theme.getSetting("your-key")method, where you’d specify your setting’s key in place of your-key.
To make a setting configurable from the portal, you must add the attribute
<setting configurable="true" key="your-key" value="your-value" />
liferay-look-and-feel.xml content might look similar to the code below, with your own
<setting> element attribute values in place of the ones specified below.
<?xml version="1.0"?> <!DOCTYPE look-and-feel PUBLIC "-//Liferay//DTD Look and Feel 6.2.0//EN" "http://www.liferay.com/dtd/liferay-look-and-feel_6_2_0.dtd"> <look-and-feel> <compatibility> <version>6.2.0+</version> </compatibility> <theme id="your-theme" name="Your Theme"> <settings> <setting configurable="true" key="your-key" value="your-value" /> </settings> </theme> </look-and-feel>
To define additional settings, add more
<setting> elements inside the
<settings></settings> tags of your
liferay-look-and-feel.xml file. To learn what other types of settings you can add to a theme, see the DTD file referenced at the beginning of this file’s contents. This DTD and all of Liferay’s definition files are available to view at https://github.com/liferay/liferay-portal/tree/6.2.x/definitions.
Any configurable settings you’ve defined are visible and ready for the site administrator to modify. In the Look and Feel section of the Site Administration → Site Pages panel, the configurable settings are visible once the site administrator selects the theme and clicks Save.
Now that you know how to add settings, you can move on to learning how to add logic to enable different templates for a theme.
Enabling Different Templates for a Theme
Say you want to be able to choose from two different page headers (perhaps one includes more details, while the other is smaller). Instead of creating two themes that are identical except for some changes in the header, you can create one and define a setting that lets you choose which header is displayed. You can follow the steps below to facilitate selecting different templates for your theme.
Make sure you have a
Create a template for each of page style choices you want to make available to configure for the theme.
For example, if you want to provide a theme template option for a detailed header for the theme and a brief header option for the same theme, you can create separate template files for them and put them in the
docroot/templates/portal_normal.[vm|ftl]file into that directory.
docroot/_diffs/templates/portal_normal.[vm|ftl]template file and add logic to use a particular template based on a theme setting.
For example, if you have a Velocity template called
header_detailed.vmthat implements the theme using a detailed header and another template called
header_brief.vmthat implements the theme using a brief header, you could implement conditional logic that chooses between the templates based on the value of a theme setting. The example Velocity code below uses the value of a setting named
header-typeto select a theme template to apply.
#if ($theme.getSetting("header-type") == "detailed") #parse ("$full_templates_path/header_detailed.vm") #else #parse ("$full_templates_path/header_brief.vm") #end
liferay-look-and-feel.xmlfile, you could add a
<theme>element for each variation of your theme, based on the templates you implemented. Make sure to use a
<setting>element with the same
key, but different
valuein each of the
Here are example
<theme>elements that both use a
keyheading-type assigned to different values.
<theme id="deep-blue" name="Deep Blue"> <settings> <setting key="header-type" value="detailed" /> </settings> </theme> <theme id="deep-blue-mini" name="Deep Blue Mini"> <settings> <setting key="header-type" value="brief" /> </settings> </theme>
Following this strategy allows the plugin to leverage the same
portal_normal.[vm|ftl] template, but apply templates based on the theme that the site administrator selects.
Congrats! Now you know how to create configurable settings for your theme and use multiple page templates from the same
portal_normal.[vm|ftl] template script!