Skip to content
Browse files

added documentation for all extensions

  • Loading branch information...
1 parent 326a3ad commit e90c5ae8b0957cd1cbfb4d45acb356952371ce8b @fabpot fabpot committed Dec 15, 2010
Showing with 205 additions and 7 deletions.
  1. +0 −7 README
  2. +23 −0 doc/debug.rst
  3. +154 −0 doc/i18n.rst
  4. +20 −0 doc/index.rst
  5. +8 −0 doc/text.rst
View
7 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.
View
23 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``.
View
154 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
View
20 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 <debug>`*: Provides tags and filters
+ to ease template debugging;
+
+* *:doc:`Twig_Extensions_Extension_Text <text>`*: Provides useful filters for
+ text manipulation;
+
+* *:doc:`Twig_Extensions_Extension_I18n <i18n>`*: Adds internationalization
+ support via the ``gettext`` library.
View
8 doc/text.rst
@@ -0,0 +1,8 @@
+The Text Extension
+==================
+
+The Text extensions provides the following filters:
+
+* ``truncate``
+* ``wordwrap``
+* ``nl2br``

0 comments on commit e90c5ae

Please sign in to comment.
Something went wrong with that request. Please try again.