======== Usage ======== Settings ------------- To use it in a Django project add `bidiutils` the project's `INSTALLED_APPS`_ setting:: INSTALLED_APPS = ( "django.contrib.auth", "django.contrib.contenttypes", "django.contrib.sites", ... "bidiutils", ... ) To enable the context processor, add it to `TEMPLATE_CONTEXT_PROCESSORS`_ settings:: TEMPLATE_CONTEXT_PROCESSORS = ( "django.core.context_processors.auth", "django.core.context_processors.debug", "django.core.context_processors.i18n", "django.core.context_processors.media", ... "bidiutils.context_processors.bidi", ) .. _TEMPLATE_CONTEXT_PROCESSORS: http://docs.djangoproject.com/en/dev/ref/settings/#template-context-processors .. _INSTALLED_APPS: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-INSTALLED_APPS Template context variables ----------------------------- If you've added `bidiutils.context_processors.bidi` to `TEMPLATE_CONTEXT_PROCESSORS` settings, you'll have additional variables in the template context for templates using a `RequestContext`_: `LANGUAGE_DIRECTION` Direction of current language (`ltr` or `rtl`). The following common idiom: .. code-block:: django {% load i18n %} Can be re-written as: .. code-block:: django {% load i18n %} `LANGUAGE_START` Start of language layout (`right` for RTL, `left` for LTR). Useful in cases you want to align elements with inline style etc: .. code-block:: django
`LANGUAGE_END` End of language layout (`left` for RTL, `right` for LTR). Just like `LANGUAGE_START`, but denotes the other side. A sample usage with `Bootstrap's glyphicons`_ to display an arrow going from language start to end: .. code-block:: django `LANGUAGE_MARKER` Language marker entity (`‏` for RTL, `‎` for LTR). Those marker are inserted into a location to make an enclosed weak character inherit its writing direction. Those are important to keep the flow correct in case of a weak directional character between to elements of the other direction. Take this template fragment for example: .. code-block:: django {{ user1.full_name }}: {{post1.title}} {{ user2.full_name }}: {{post2.title}} assuming your current language's direction is RTL, and user2's full name and post title are in LTR (e.g: both in English) while user one's are RTL The result will be rendered as (using UPPERCASE without actual content do demonstrate):: USER1_POST_TITLE :USER1_FULLNAME USER2_FULLNAME: USER2_POST_TITLE This is because the ':' is weak character inheriting the direction for surrounding element(s). Inserting the current language marker ensures the correct layout .. code-block:: django {{ user1.full_name }}{{LANGUAGE_MARKER}}: {{post1.title}} {{ user2.full_name }}{{LANGUAGE_MARKER}}: {{post2.title}} For more information see `Bi-Directional text - Unicode support`_. .. _RequestContext: https://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext .. _Bi-Directional text - Unicode support: http://en.wikipedia.org/wiki/Bi-directional_text#Unicode_support .. _Bootstrap's glyphicons: http://getbootstrap.com/components/#glyphicons `add_direction` filter ------------------------- Adds direction to the element. Make sure to load `bidiutils_tags` to use the filter which accepts a single, optional, argument: `rtl_only` Add the direction only in case of a right-to-left language. The default if no argument is passed. `both` Add the direction in both cases `ltr_only` Add the direction only in case of a left-to-right language Assuming the current language is RTL, and `image` in the context is `"arrow.png"`: .. code-block:: django {% load bidiutils_tags %} arrow arrow arrow arrow The rendered result will be: .. code-block:: html arrow arrow arrow arrow On the other hand, Assuming the current language is LTR, and `image` in the context is `"arrow.png"`, the rendered result of the above template would be: .. code-block:: html arrow arrow arrow arrow