From e90c5ae8b0957cd1cbfb4d45acb356952371ce8b Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Wed, 15 Dec 2010 10:02:37 +0100 Subject: [PATCH] added documentation for all extensions --- README | 7 --- doc/debug.rst | 23 ++++++++ doc/i18n.rst | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 20 +++++++ doc/text.rst | 8 +++ 5 files changed, 205 insertions(+), 7 deletions(-) create mode 100644 doc/debug.rst create mode 100644 doc/i18n.rst create mode 100644 doc/index.rst create mode 100644 doc/text.rst diff --git a/README b/README index 813f074c..a78292c9 100644 --- a/README +++ b/README @@ -4,11 +4,4 @@ Twig Extensions Repository This repository hosts Twig Extensions that do not belong to the core but can be nonetheless interesting to share with other developers. -This extension adds the following filters - -* truncate -* wordwrap -* n12br -* sluggize - Fork this repository, add your extension, and request a pull. diff --git a/doc/debug.rst b/doc/debug.rst new file mode 100644 index 00000000..1831a2fb --- /dev/null +++ b/doc/debug.rst @@ -0,0 +1,23 @@ +The Debug Extension +=================== + +The ``debug`` extension provides a ``debug`` tag that can be used to +output the content of the current context: + +.. code-block:: jinja + + {% debug %} + +This is really useful when a template does not work as expected. You can also +output a specific variable or an expression: + +.. code-block:: jinja + + {% debug items %} + + {% debug post.body %} + +.. warning:: + + The ``debug`` tag only works when the ``debug`` environment option is set + to ``true``. diff --git a/doc/i18n.rst b/doc/i18n.rst new file mode 100644 index 00000000..80506c0f --- /dev/null +++ b/doc/i18n.rst @@ -0,0 +1,154 @@ +The i18n Extension +================== + +Configuration +------------- + +The ``i18n`` extension adds `gettext`_ support to Twig. It defines one tag, +``trans``. + +You need to register this extension before using the ``trans`` block:: + + $twig->addExtension(new Twig_Extensions_Extension_I18n()); + +Note that you must configure the ``gettext`` extension before rendering any +internationalized template. Here is a simple configuration example from the +PHP `documentation`_:: + + // Set language to French + putenv('LC_ALL=fr_FR'); + setlocale(LC_ALL, 'fr_FR'); + + // Specify the location of the translation tables + bindtextdomain('myAppPhp', 'includes/locale'); + bind_textdomain_codeset('myAppPhp', 'UTF-8'); + + // Choose domain + textdomain('myAppPhp'); + +.. caution:: + + The ``i18n`` extension only works if the PHP `gettext`_ extension is + enabled. + +Usage +----- + +Use the ``trans`` block to mark parts in the template as translatable: + +.. code-block: jinja + + {% trans "Hello World!" %} + + {% trans string_var %} + + {% trans %} + Hello World! + {% endtrans %} + +In a translatable string, you can embed variables: + +.. code-block: jinja + + {% trans %} + Hello {{ name }}! + {% endtrans %} + +.. note:: + + ``{% trans "Hello {{ name }}!" %}`` is not a valid statement. + +If you need to apply filters to the variables, you first need to assign the +result to a variable: + +.. code-block: jinja + + {% set name = name|capitalize %} + + {% trans %} + Hello {{ name }}! + {% endtrans %} + +To pluralize a translatable string, use the ``plural`` block: + +.. code-block: jinja + + {% trans %} + Hey {{ name }}, I have one apple. + {% plural apple_count %} + Hey {{ name }}, I have {{ count }} apples. + {% endtrans %} + +The ``plural`` tag should provide the ``count`` used to select the right +string. Within the translatable string, the special ``count`` variable always +contain the count value (here the value of ``apple_count``). + +Within an expression or in a tag, you can use the ``trans`` filter to translate +simple strings or variables: + +.. code-block: jinja + + {{ var|default(default_value|trans) }} + +Complex Translations within an Expression or Tag +------------------------------------------------ + +Translations can be done with both the ``trans`` tag and the ``trans`` filter. +The filter is less powerful as it only works for simple variables or strings. +For more complex scenario, like pluralization, you can use a two-step +strategy: + +.. code-block: jinja + + {# assign the translation to a temporary variable #} + {% set default_value %} + {% trans %} + Hey {{ name }}, I have one apple. + {% plural apple_count %} + Hey {{ name }}, I have {{ count }} apples. + {% endtrans %} + {% endset %} + + {# use the temporary variable within an expression #} + {{ var|default(default_value|trans) }} + +Extracting Template Strings +--------------------------- + +If you use the Twig I18n extension, you will probably need to extract the +template strings at some point. Unfortunately, the ``xgettext`` utility does +not understand Twig templates natively. But there is a simple workaround: as +Twig converts templates to PHP files, you can use ``xgettext`` on the template +cache instead. + +Create a script that forces the generation of the cache for all your +templates. Here is a simple example to get you started:: + + $tplDir = dirname(__FILE__).'/templates'; + $tmpDir = '/tmp/cache/'; + $loader = new Twig_Loader_Filesystem($tplDir); + + // force auto-reload to always have the latest version of the template + $twig = new Twig_Environment($loader, array( + 'cache' => $tmpDir, + 'auto_reload' => true + )); + $twig->addExtension(new Twig_Extensions_Extension_I18n()); + // configure Twig the way you want + + // iterate over all your templates + foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($tplDir), RecursiveIteratorIterator::LEAVES_ONLY) as $file) + { + // force compilation + $twig->loadTemplate(str_replace($tplDir.'/', '', $file)); + } + +Use the standard ``xgettext`` utility as you would have done with plain PHP +code: + +.. code-block: plain + + xgettext --default-domain=messages -p ./locale --from-code=UTF-8 -n --omit-header -L PHP /tmp/cache/*.php + +.. _`gettext`: http://www.php.net/gettext +.. _`documentation`: http://fr.php.net/manual/en/function.gettext.php diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..456e73b1 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,20 @@ +Twig Extensions +=============== + +.. toctree:: + :hidden: + + debug + text + i18n + +The Twig Extensions repository provides several useful extensions for Twig: + +* *:doc:`Twig_Extensions_Extension_Debug `*: Provides tags and filters + to ease template debugging; + +* *:doc:`Twig_Extensions_Extension_Text `*: Provides useful filters for + text manipulation; + +* *:doc:`Twig_Extensions_Extension_I18n `*: Adds internationalization + support via the ``gettext`` library. diff --git a/doc/text.rst b/doc/text.rst new file mode 100644 index 00000000..ee96a5f6 --- /dev/null +++ b/doc/text.rst @@ -0,0 +1,8 @@ +The Text Extension +================== + +The Text extensions provides the following filters: + +* ``truncate`` +* ``wordwrap`` +* ``nl2br``