Right-to-Left Languages
Right-to-left (RTL) support refers to the ability of a library, website, or application to handle and respond to users who communicate through a right-to-left language such as Arabic, Hebrew, Chinese or Japanese.
The default language input for most users of the web is left-to-right. However, many websites and applications wish to also provide RTL support for their visitors. The RTL functionality falls more into the internationalization space but can be considered as an accessibility feature as well. After all, RTL is about making user experiences more accessible for visitors who use right-to-left languages.
Configuration
Unless you are building an application that exclusively uses RTL languages, it is intuitive to apply the RTL support feature based on external input, such as language selection or information from the user agent of a visitor. In that case, you can apply the k-rtl class at runtime using the jQuery addClass method.
For example, if you want to allow the user to trigger RTL support by selecting a language from a drop-down list or by clicking a button:
- Add a button to your page by using the
<input type="button" id="toggleRTL" value="Activate RTL Support" class="k-button" />setting. -
Add a click handler for the button and toggle RTL support by adding or removing the
k-rtlclass to a form—in this case, a collection of form fields to which you assigned an ID ofspeakerForm. With that handler in place, the user can now trigger RTL support on demand.$('#toggleRTL').on('click', function(event) { var form = $('#speakerForm'); if (form.hasClass('k-rtl')) { form.removeClass('k-rtl') } else { form.addClass('k-rtl'); } })
Adding the Styles
You also need to configure your project with the proper styles for the RTL rendering of the content.
Setup
Wrap the Kendo UI widgets in an HTML element with the k-rtl CSS class. Assign this class to the <body> tag so that no additional DOM elements are required.
The `k-rtl` class has the following effects:
* Applies a `direction:rtl` style, so you do not have to set it yourself when creating right-to-left applications.
* Causes the widgets to change their layout in accordance with the common RTL conventions.
* Helps widget scripts to detect the RTL mode and, accordingly, widgets change their behavior.
<body class="k-rtl">
<!-- Your Amazing App -->
</body>
Known Limitations
- Vertical scrollbar position may be on the left or right side depending on the used browser. This cannot be controlled via CSS or script.
- The layout of the Kendo UI ListView widget depends entirely on the defined template. The widget itself does nothing to convert an existing LTR template to RTL layout. If a
k-rtlCSS class is present and applied to a wrapper element, text direction will be reversed, but floats, margins, paddings, etc., will keep their orientation. - Kendo UI Splitter does not reverse the order of its panes in RTL mode.
For more information on appearance and layout in Kendo UI, refer to the article on the themes and styles Kendo UI supports.
Automatic Implementation
Your project might require you to trigger the RTL support automatically and not upon user interaction. In such cases, you can inspect the Accept-Language HTTP header to determine if a user prefers an RTL language.
The Accept-Language header is provided with every HTTP request, and is typically exposed as a property on a request object in server-side frameworks. If you are using ASP.NET, for instance, you can access the Accept-Language header by calling userLangs = Request.Headers["Accept-Language"];.
For PHP, use the $_SERVER object—userLangs = $_SERVER['HTTP_ACCEPT_LANGUAGE'];. For Rails applications, use the request.env object—userLangs = request.env["HTTP_ACCEPT_LANGUAGE"].
The Accept-Language header may return a comma-separated list of languages, ordered by preference. In such cases, you have to split the returned value into an array or list and inspect the first element to determine if adding the k-rtl class to the returned markup is necessary.