Conversion Diaries

Implementing RTL Support in Adobe Experience Manager (AEM) for Global Accessibility

•

Dorian Regester

Introduction

In today’s interconnected digital world, ensuring that your website is accessible to all users, regardless of their language, is crucial. For businesses and organizations operating on a global scale, supporting Right-to-Left (RTL) languages such as Arabic, Hebrew, and Persian is essential. Adobe Experience Manager (AEM) provides a flexible platform for managing digital content but implementing RTL support often requires additional customization. This guide will outline the necessary steps to effectively support RTL languages in AEM, ensuring a seamless experience for both content authors and end users.

Problem Statement or Background

The digital content landscape is increasingly diverse, with many users accessing websites in RTL languages. While AEM offers some built-in capabilities to handle RTL content, these features often require further refinement to meet the needs of RTL language speakers fully. RTL support goes beyond simple text alignment; it involves mirroring the entire user interface, including navigation menus, buttons, and icons. This challenge must be addressed from both the end-user experience and the content authoring perspective to ensure a comprehensive solution.

Key Concepts or Terminology

  1. RTL (Right-to-Left) Languages: Languages that are read and written from right to left, such as Arabic, Hebrew, and Persian.
  2. LTR (Left-to-Right) Languages: Languages that are read and written from left to right, such as English, French, and Spanish.
  3. ClientLib: A collection of CSS and JavaScript files used in AEM to manage styles and scripts across web pages.
  4. Sling Model: A mechanism in AEM for creating Java objects that interact with Sling’s resource and request layers.
  5. Experience Fragment (XF): A reusable piece of content within AEM that can be used across various pages or sites.
  6. Content Fragment (CF): A modular piece of content designed for reuse across different channels or platforms.

Detailed Explanation

Supporting RTL in AEM requires addressing two main perspectives: the end-user experience and the content authoring experience. Each perspective demands specific strategies to ensure that RTL support is fully integrated into your AEM environment.

End User Experience

For the end user, it is crucial to adjust the text direction and overall layout based on the language settings. This involves setting the correct direction attribute on the HTML tag and adapting CSS styles to handle RTL layouts. Here’s how you can achieve this:

Content Authoring Experience

Content authors must be able to work effectively with RTL content. This includes ensuring that authoring tools and components, such as the Rich Text Editor (RTE), support RTL text and layout properly.

Step-by-Step Guide

1. Setting Direction for End Users

Creating a Sling Model:

To dynamically adjust text direction based on page language, you need to create a Sling Model. This model will fetch the language setting from page properties and return the appropriate direction value.

javaCopy codepackage com.adobe.aem.guides.wknd.core.models;

import org.apache.sling.api.resource.Resource;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.injectorspecific.SlingObject;

import javax.inject.Inject;
import java.util.Arrays;
import java.util.List;

@Model(adaptables = Resource.class)
public class LanguageHelper {

    private static final List<String> RTL_LANGUAGES = Arrays.asList("ar", "he", "fa", "ur");

    @SlingObject
    private Resource currentResource;

    public String getDirection() {
        String language = currentResource.getValueMap().get("jcr:language", String.class);
        if (language != null) {
            String primaryLanguage = language.split("_")[0];
            return RTL_LANGUAGES.contains(primaryLanguage) ? "rtl" : "ltr";
        }
        return "ltr";
    }
}

Updating Page Rendering Component:

Modify the page.html file to include the direction attribute based on the LanguageHelper model.

htmlCopy code<html data-sly-use.page="com.adobe.cq.wcm.core.components.models.Page" lang="${page.language}"
      data-sly-use.pwa="com.adobe.cq.wcm.core.components.models.PWA"
      data-sly-use.head="head.html"
      data-sly-use.footer="footer.html"
      data-sly-use.redirect="redirect.html"
      data-sly-use.langHelper="com.adobe.aem.guides.wknd.core.models.LanguageHelper" dir="${langHelper.direction}">

2. Adapting CSS for RTL

Generating RTL CSS:

To ensure proper styling for RTL pages, create RTL-specific versions of your CSS files. Tools like rtlcss-webpack-plugin can automate this process.

Install the Plugin:

bashCopy codenpm install rtlcss-webpack-plugin --save-dev

Modify webpack.common.js:

javascriptCopy codeconst RtlCssPlugin = require('rtlcss-webpack-plugin');

module.exports = {
  // existing configuration
  plugins: [
    // other plugins
    new RtlCssPlugin({
      filename: 'clientlib-[name]/[name]-rtl.css'
    })
  ]
};

Update clientlib.config.js:

jsonCopy code{
  "name": "clientlib-site-rtl",
  "categories": ["wknd.site.rtl"],
  "assets": {
    "css": {
      "cwd": "clientlib-site",
      "files": ["**/*rtl.css"],
      "flatten": false
    }
  }
}

Including RTL ClientLibs:

Modify headlibs.html to dynamically include the correct client libraries based on the page direction.

htmlCopy code<sly data-sly-use.langHelper="com.adobe.aem.guides.wknd.core.models.LanguageHelper"></sly>
<sly data-sly-test="${clientLibCategories}" 
     data-sly-use.rtlClientLibCSSProvider="${'com.adobe.aem.guides.wknd.core.models.RTLClientLibCSSProvider' @ cssClientLibs=clientLibCategories, dir=langHelper.direction}" 
     data-sly-unwrap></sly>
<sly data-sly-test="${rtlClientLibCSSProvider.rtlClientLibs}" data-sly-call="${clientlib.css @ categories=rtlClientLibCSSProvider.rtlClientLibs}"></sly>

3. Supporting RTL in Authoring

Custom ClientLibrary for Authoring:

To support RTL in the authoring environment, create a custom client library that includes JavaScript to handle RTL settings in the Rich Text Editor.

javascriptCopy code(function ($, document, ns) {
  $(document).on("dialog-ready", function () {
    var language =
      Granite.author.ContentFrame.contentWindow.document.documentElement.lang;
    if (language) {
      var primaryLanguageCode = language.split("-")[0];
      var rtlLanguages = ["ar", "he", "fa", "ur"];
      var isRtl = rtlLanguages.indexOf(primaryLanguageCode) !== -1;

      if (isRtl) {
        var richtextElement = document.querySelector(".coral-RichText");
        if (richtextElement) {
          richtextElement.style.textAlign = "right";
          richtextElement.style.direction = "rtl";
        }
      }
    }
  });
})(Granite.$, document, Granite.author);

Adapting Experience Fragments:

For Experience Fragments (XFs), add direction logic based on the XF properties in xfpage.html.

htmlCopy code<!DOCTYPE HTML>
<html data-sly-use.langHelper="com.adobe.aem.guides.wknd.core.models.LanguageHelper" dir="${langHelper.direction}">
 <head data-sly-include="head.html"></head>
 <body data-sly-use.body="body.js" class="${body.cssClasses}"
 data-sly-include="body.html"></body>
</html>

Content Fragments:

For the old Content Fragment editor, use a custom client library to manage RTL direction based on URL parameters.

javascriptCopy code(function ($, $document) {
    $document.on("foundation-contentloaded", onContentLoad);

    function onContentLoad(event) {
        var urlParams = new URLSearchParams(window.location.search);
        var direction = urlParams.get('direction');

        var elements = document.querySelectorAll('.coral-Form-fieldwrapper, .cfm-multieditor-fullscreen-richtext-editor-wrapper');
        
        elements.forEach(function(element) {
            element.setAttribute('dir', direction);
        });
    }
}(jQuery, jQuery(document)));

Best Practices or Tips

  1. Use Logical Properties: CSS logical properties like padding-inline-start are direction-agnostic and reduce the need for separate RTL overrides.
  2. Thorough Testing: Conduct comprehensive testing across different devices and browsers to ensure RTL support is consistent and functional.
  3. Organize ClientLibs: Maintain separate ClientLib categories for RTL and LTR styles to streamline management and updates.
  4. Update Authoring Tools: Regularly review and update authoring tools and components to ensure RTL support is integrated throughout the authoring environment.

Case Studies or Examples

  1. Multinational Corporate Website: A global enterprise successfully adapted their AEM site to support multiple RTL languages using the strategies outlined above. They observed improved user engagement and accessibility due to a more user-friendly interface tailored to RTL readers.
  2. Regional News Portal: A news portal serving RTL-speaking regions implemented RTL support to enhance readability and navigation. By following these steps, they ensured a consistent and intuitive experience for their diverse audience.

Troubleshooting and FAQ

Q1: What if my RTL styles are not applied correctly?

A1: Ensure that RTL-specific CSS files are correctly generated and included. Verify that the dir attribute is set properly in your HTML and that the RTL styles are not being overridden by LTR styles.

Q2: How can I ensure RTL support in dynamic content?

A2: Use dynamic logic in your client libraries to apply RTL styles based on the language settings. Regularly test dynamic content to confirm that RTL settings are applied correctly.

Q3: Are there any tools that can help with RTL CSS generation?

A3: Yes, tools like rtlcss-webpack-plugin can automate the generation of RTL CSS files. Make sure to configure these tools correctly in your build process.

By following this guide, you can enhance your AEM site’s global reach by providing comprehensive RTL language support, ensuring a seamless and inclusive experience for all users.

Conclusion

Implementing RTL support in Adobe Experience Manager (AEM) is crucial for ensuring that your website is accessible and user-friendly for audiences who read and write in RTL languages. By addressing both the end-user experience and content authoring processes, you can create a seamless and effective RTL experience.

Key Takeaways:

  1. Dynamic Direction Handling: Utilize Sling Models to dynamically adjust the text direction based on the page’s language settings. This ensures that content is presented correctly to users reading RTL languages.
  2. CSS Adaptation: Create and manage RTL-specific CSS files to handle layout adjustments. Tools like rtlcss-webpack-plugin can streamline this process, making it easier to maintain a consistent appearance across RTL and LTR layouts.
  3. Enhanced Authoring Experience: Adapt authoring tools and content fragments to support RTL languages. Custom JavaScript and CSS modifications in the authoring environment ensure that content creators can work effectively with RTL content.
  4. Testing and Best Practices: Regularly test your site across different devices and browsers to ensure that RTL support is functioning as intended. Follow best practices such as using logical CSS properties and keeping your ClientLibs organized to facilitate ongoing maintenance and updates.

By following these strategies, you not only enhance the accessibility of your digital content but also improve user satisfaction and engagement across diverse linguistic and cultural contexts. RTL support is more than just a feature—it’s a commitment to inclusivity and global reach, ensuring that your content resonates with all audiences, regardless of their language.

Implementing these practices effectively will position your organization as a leader in delivering a truly global user experience, reflecting a commitment to catering to all users, irrespective of their language preferences.

Leave a Reply

Your email address will not be published. Required fields are marked *