Middle Eastern languages such as Hebrew and Arabic are written right-to-left (RTL). Many sites that use RTL languages are multilingual, requiring both RTL and left-to-right (LTR) content. Modern browsers support language and direction HTML attributes to adapt and align page content automatically. Sites, however, may consist of elements that are absolutely positioned on the page by a style sheet: these elements aren’t automatically aligned by the browser. Instead, you must adapt your style sheets to handle such elements. Since style sheets are usually designed for LTR languages, the typical challenge is to create alternative versions of the CSS for RTL languages. This can be an arduous task.
Thankfully, Liferay’s Right to Left Language Support app automatically adapts Liferay Portal styles for RTL languages. When you deploy it, it mirrors your site’s content for RTL languages. The app is available on the Liferay Marketplace. You can purchase, install, and deploy the app as described in the Leveraging the Liferay Marketplace chapter of Using Liferay Portal.
As a before-and-after example, the figure below shows a page displayed in English, an LTR language.
Figure 1: Here is a site displaying English content left-to-right.
Compare it to the following figure of a page displayed in Hebrew, an RTL language.
Figure 2: Here is a site displaying Hebrew content right-to-left using Right to Left Language Support.
You get the point, right? The Right to Left Language Support (RTL Support) app does the heavy lifting of rendering the RTL content appropriately!
Note: RTL Support has been integrated into Liferay Portal 6.2 EE with portal-50-6210 (or higher) and Liferay Portal 6.2 CE GA5 (or later). The portal will contain RTL support without further configuration, and there is no further need to deploy this standalone app.
Now that you’ve seen Liferay Portal and its apps rendered using RTL Support, have you wondered how you might leverage RTL Support in your custom plugins? You’ll learn how to use RTL Support with your plugins next.
Applying the RTL Support to Custom Plugins
You can use RTL Support with any plugin type, though theme plugins are the most common. The following steps focus on using RTL Support in a custom theme, but they also mention what’s needed to make similar changes to support using RTL Support in the other plugin types.
Step 1: Deploy the Right to Left Language Support app to your application server.
If upon initial deployment you don’t notice any changes when switching to an RTL language, reload the page to force a clean cache.
Note: since dynamic generation of CSS from SASS is not yet supported in the
context of the RTL Support app, the hook loads the current theme’s merged
CSS files, disregarding whether
theme CSS fast loading
is disabled. Disabling CSS fast load (i.e., setting
theme.css.fast.load=false)
is commonly done while debugging for development.
Now that you have deployed the RTL language support app, restart your application server.
Step 2: Extract the contents of the Liferay RTL Hook web application.
Copy the rtl-hook.jar and its dependencies, ant.jar, jodd.jar, jruby.jar
and rhino.jar, from your RTL hook web app’s WEB-INF/lib folder to the
docroot/WEB-INF/lib folder of your plugin project.
Step 3: Modify Your web.xml and build.xml for RTL Language Support.
You’ll have to add some code to your web.xml and build.xml in order for the
RTL Language Support app to work. Here are some filtering elements that must
be added to your web.xml before the closing </web-app> tag in your project’s
docroot/WEB-INF/web.xml file:
<filter>
<filter-name>Dynamic CSS Filter</filter-name>
<filter-class>
com.liferay.rtl.hook.filter.dynamiccss.DynamicCSSFilter
</filter-class>
</filter>
<filter-mapping>
<filter-name>Dynamic CSS Filter</filter-name>
<url-pattern>*.css</url-pattern>
</filter-mapping>
Some targets must be added to your build.xml so the RTL CSS files can be built
and cleaned. The following snippet is example code showing targets for a theme
plugin project’s build.xml:
<target name="build-css"
depends="clean-rtl-css, build-common-theme.build-css, build-rtl-css"
/>
<target name="build-rtl-css">
<java
classname="com.liferay.rtl.tools.RtlCssBuilder"
classpathref="plugin.classpath"
fork="true"
newenvironment="true"
>
<jvmarg value="-Dliferay.lib.portal.dir=${app.server.lib.portal.dir}" />
<arg value="sass.dir=/" />
<arg value="sass.docroot.dir=${basedir}/docroot" />
</java>
</target>
<target name="clean-rtl-css">
<delete failonerror="false" includeemptydirs="true">
<fileset dir="${basedir}/docroot" includes="**/.sass-cache/*_rtl.*" />
</delete>
</target>
If you’re using the RTL Language Support app with another type of plugin project,
rename the build-common-theme.build-css dependency target reference
appropriately for your plugin type:
Portlet: build-common-portlet.build-css
Hook: build-common-hook.build-css
Ext: build-common-ext.build-css
Web App: build-common-web.build-css
Step 4: Deploy your plugin to the portal.
After you’ve deployed your plugin, you’ll notice that ant echoes
Generated RTL cache for … messages that mention the cache that the RTL hook
generates in your plugin. In your plugin’s css/.sass-cache folder, the hook
creates *_rtl.css versions of each of your *.css files.
You now know how to use the Right to Left Language Support app in your custom plugins. Now it’s time to learn how you can extend the Right to Left Language Support app’s style with your own custom CSS for RTL languages.
Defining Custom CSS for RTL Languages
As you learned in the previous section, the Right to Left Language Support (RTL
Support) app automatically generates RTL versions of your CSS files by applying
rules, such as changing margin-left to margin-right. You may, however, want
to extend the generated CSS by defining your own custom styles for RTL
languages. You can achieve this by following the steps below.
Step 1: Create a CSS File to Extend the Original and Make Your Edits.
You’ll need to create a CSS file with the suffix _rtl in the same location as
a CSS file that you want to extend. For example, create a file main_rtl.css
to extend a file named main.css.
Once you have made the _rtl version of the CSS you want to extend, edit the
_rtl file, adding only your custom styles for RTL languages.
Step 2: Deploy your Plugin and Test It.
After you have deployed your plugin, check its css/.sass-cache folder to see
that the generated _rtl.css file not only contains the CSS from the original
file, but also contains your custom CSS code at the end.
Add the Language portlet to a page and change the current language to an RTL language (e.g., Hebrew) to see your custom RTL styles.
In this tutorial, you’ve learned how to adapt your plugin styles for RTL languages, and how to define custom styles for RTL languages. Whether you want to adapt the portal and/or your custom plugins to RTL languages, the RTL Support app makes it easy to offer your users the ideal viewing experience.
Related Topics
As you can see, hooks are a useful way of modifying your portal. Here are some other tutorials about hooks: