Follow up r78101.

[lhc/web/wiklou.git] / includes / Xml.php

diff --git a/includes/Xml.php b/includes/Xml.php
index 4dfc9e6..65f2010 100644 (file)
--- a/includes/Xml.php
+++ b/includes/Xml.php
@@ -81,7 +81,7 @@ class Xml {
        /**
         * This opens an XML element
         *
-        * @param $element name of the element
+        * @param $element String name of the element
         * @param $attribs array of attributes, see Xml::expandAttributes()
         * @return string
         */
@@ -91,7 +91,7 @@ class Xml {
 
        /**
         * Shortcut to close an XML element
-        * @param $element element name
+        * @param $element String element name
         * @return string
         */
        public static function closeElement( $element ) { return "</$element>"; }
@@ -100,9 +100,9 @@ class Xml {
         * Same as Xml::element(), but does not escape contents. Handy when the
         * content you have is already valid xml.
         *
-        * @param $element element name
+        * @param $element String element name
         * @param $attribs array of attributes
-        * @param $contents content of the element
+        * @param $contents String content of the element
         * @return string
         */
        public static function tags( $element, $attribs = null, $contents ) {
@@ -248,8 +248,8 @@ class Xml {
 
        /**
         * Shortcut to make a span element
-        * @param $text content of the element, will be escaped
-        * @param $class class name of the span element
+        * @param $text String content of the element, will be escaped
+        * @param $class String class name of the span element
         * @param $attribs other attributes
         * @return string
         */
@@ -271,7 +271,7 @@ class Xml {
 
        /**
         * Convenience function to build an HTML text input field
-        * @param $name value of the name attribute
+        * @param $name String value of the name attribute
         * @param $size value of the size attribute
         * @param $value value of the value attribute
         * @param $attribs other attributes
@@ -313,9 +313,9 @@ class Xml {
 
        /**
         * Convenience function to build an HTML checkbox
-        * @param $name value of the name attribute
-        * @param $checked Whether the checkbox is checked or not
-        * @param $attribs other attributes
+        * @param $name String value of the name attribute
+        * @param $checked Bool Whether the checkbox is checked or not
+        * @param $attribs Array other attributes
         * @return string HTML
         */
        public static function check( $name, $checked=false, $attribs=array() ) {
@@ -345,9 +345,12 @@ class Xml {
 
        /**
         * Convenience function to build an HTML form label
-        * @param $label text of the label
+        * @param $label String text of the label
         * @param $id
-        * @param $attribs Array, other attributes
+        * @param $attribs Array an attribute array.  This will usuall be 
+        *     the same array as is passed to the corresponding input element,
+        *     so this function will cherry-pick appropriate attributes to 
+        *     apply to the label as well; currently only class is applied.
         * @return string HTML
         */
        public static function label( $label, $id, $attribs=array() ) {
@@ -360,9 +363,9 @@ class Xml {
 
        /**
         * Convenience function to build an HTML text input field with a label
-        * @param $label text of the label
-        * @param $name value of the name attribute
-        * @param $id id of the input
+        * @param $label String text of the label
+        * @param $name String value of the name attribute
+        * @param $id String id of the input
         * @param $size value of the size attribute
         * @param $value value of the value attribute
         * @param $attribs other attributes
@@ -451,7 +454,6 @@ class Xml {
         * @return string
         */
        public static function listDropDown( $name= '', $list = '', $other = '', $selected = '', $class = '', $tabindex = Null ) {
-               $options = '';
                $optgroup = false;
 
                $options = self::option( $other, 'other', $selected === 'other' );
@@ -595,6 +597,8 @@ class Xml {
                                $s .= self::encodeJsVar( $elt );
                        }
                        $s .= ']';
+               } elseif ( $value instanceof XmlJsCode ) {
+                       $s = $value->value;
                } elseif ( is_object( $value ) || is_array( $value ) ) {
                        // Objects and associative arrays
                        $s = '{';
@@ -612,6 +616,30 @@ class Xml {
                return $s;
        }
 
+       /**
+        * Create a call to a JavaScript function. The supplied arguments will be 
+        * encoded using Xml::encodeJsVar(). 
+        *
+        * @param $name The name of the function to call, or a JavaScript expression
+        *    which evaluates to a function object which is called.
+        * @param $args Array of arguments to pass to the function.
+        * @since 1.17
+        */
+       public static function encodeJsCall( $name, $args ) {
+               $s = "$name(";
+               $first = true;
+               foreach ( $args as $arg ) {
+                       if ( $first ) {
+                               $first = false;
+                       } else {
+                               $s .= ', ';
+                       }
+                       $s .= Xml::encodeJsVar( $arg );
+               }
+               $s .= ");\n";
+               return $s;
+       }
+
 
        /**
         * Check if a string is well-formed XML.
@@ -674,8 +702,8 @@ class Xml {
        /**
        * Generate a form (without the opening form element).
        * Output optionally includes a submit button.
-       * @param $fields Associative array, key is message corresponding to a description for the field (colon is in the message), value is appropriate input.
-       * @param $submitLabel A message containing a label for the submit button.
+       * @param $fields Array Associative array, key is message corresponding to a description for the field (colon is in the message), value is appropriate input.
+       * @param $submitLabel String A message containing a label for the submit button.
        * @return string HTML form.
        */
        public static function buildForm( $fields, $submitLabel = null ) {
@@ -814,3 +842,23 @@ class XmlSelect {
        }
 
 }
+
+/**
+ * A wrapper class which causes Xml::encodeJsVar() and Xml::encodeJsCall() to 
+ * interpret a given string as being a JavaScript expression, instead of string 
+ * data.
+ *
+ * Example:
+ *
+ *    Xml::encodeJsVar( new XmlJsCode( 'a + b' ) );
+ *
+ * Returns "a + b".
+ * @since 1.17
+ */
+class XmlJsCode {
+       public $value;
+
+       function __construct( $value ) {
+               $this->value = $value;
+       }
+}