From: Tim Starling <tstarling@users.mediawiki.org>
Date: Wed, 23 Jul 2008 14:51:39 +0000 (+0000)
Subject: Some documentation for SFH_OBJECT_ARGS
X-Git-Tag: 1.31.0-rc.0~46406
X-Git-Url: http://git.cyclocoop.org/%22.%24image2.%22?a=commitdiff_plain;h=3e541d529b3e22dfc6cfd2246177807745e0e4e1;p=lhc%2Fweb%2Fwiklou.git

Some documentation for SFH_OBJECT_ARGS
---

diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index c1c48866ea..b9e0ceef98 100644
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -3947,6 +3947,9 @@ class Parser
 	 * The callback function should have the form:
 	 *    function myParserFunction( &$parser, $arg1, $arg2, $arg3 ) { ... }
 	 *
+	 * Or with SFH_OBJECT_ARGS:
+	 *    function myParserFunction( $parser, $frame, $args ) { ... }
+	 *
 	 * The callback may either return the text result of the function, or an array with the text
 	 * in element 0, and a number of flags in the other elements. The names of the flags are
 	 * specified in the keys. Valid flags are:
@@ -3960,7 +3963,26 @@ class Parser
 	 * @param string $id The magic word ID
 	 * @param mixed $callback The callback function (and object) to use
 	 * @param integer $flags a combination of the following flags:
-	 *                SFH_NO_HASH No leading hash, i.e. {{plural:...}} instead of {{#if:...}}
+	 *     SFH_NO_HASH   No leading hash, i.e. {{plural:...}} instead of {{#if:...}}
+	 *
+	 *     SFH_OBJECT_ARGS   Pass the template arguments as PPNode objects instead of text. This 
+	 *     allows for conditional expansion of the parse tree, allowing you to eliminate dead
+	 *     branches and thus speed up parsing. It is also possible to analyse the parse tree of 
+	 *     the arguments, and to control the way they are expanded.
+	 *
+	 *     The $frame parameter is a PPFrame. This can be used to produce expanded text from the
+	 *     arguments, for instance:
+	 *         $text = isset( $args[0] ) ? $frame->expand( $args[0] ) : '';
+	 *
+	 *     For technical reasons, $args[0] is pre-expanded and will be a string. This may change in 
+	 *     future versions. Please call $frame->expand() on it anyway so that your code keeps
+	 *     working if/when this is changed.
+	 *
+	 *     If you want whitespace to be trimmed from $args, you need to do it yourself, post-
+	 *     expansion.
+	 *
+	 *     Please read the documentation in includes/parser/Preprocessor.php for more information 
+	 *     about the methods available in PPFrame and PPNode.
 	 *
 	 * @return The old callback function for this name, if any
 	 */