From da06f5903356db8bfff170861f178db916f37605 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 4 Jul 2013 13:06:36 -0400 Subject: [PATCH] Add more complete documentation for building tests. --- doc/advanced.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 53 insertions(+), 1 deletions(-) diff --git a/doc/advanced.rst b/doc/advanced.rst index 3c06338..804f50c 100644 --- a/doc/advanced.rst +++ b/doc/advanced.rst @@ -277,7 +277,59 @@ to create an instance of ``Twig_SimpleTest``:: }); $twig->addTest($test); -Tests do not support any options. +Tests allow you to create custom application specific logic for evaluating +boolean conditions. As a simple, example let's create a Twig test that checks if +objects are 'red':: + + $twig = new Twig_Environment($loader) + $test = new Twig_SimpleTest('red', function ($value) { + if (isset($value->color) && $value->color == 'red') { + return true; + } + if (isset($value->paint) && $value->paint == 'red') { + return true; + } + return false; + }); + $twig->addTest($test); + +Test functions should always return true/false. + +When creating tests you can use the ``node_class`` option to provide custom test +compilation. This is useful if your test can be compiled into PHP primitives. +This is used by many of the tests built into Twig:: + + $twig = new Twig_Environment($loader) + $test = new Twig_SimpleTest( + 'odd', + null, + array('node_class' => 'Twig_Node_Expression_Test_Odd')); + $twig->addTest($test); + + class Twig_Node_Expression_Test_Odd extends Twig_Node_Expression_Test + { + public function compile(Twig_Compiler $compiler) + { + $compiler + ->raw('(') + ->subcompile($this->getNode('node')) + ->raw(' % 2 == 1') + ->raw(')') + ; + } + } + +The above example, shows how you can create tests that use a node class. The +node class has access to one sub-node called 'node'. This sub-node contains the +value that is being tested. When the ``odd`` filter is used in code like: + +.. code-block:: jinja + + {% if my_value is odd %} + +The ``node`` sub-node will contain an expression of ``my_value``. Node based +tests also have access to the ``arguments`` node. This node will contain the +various other arguments that have been provided to your test. Tags ---- -- 1.7.2.5