Improve documentation of content handler stuff

[lhc/web/wiklou.git] / includes / content / TextContent.php

diff --git a/includes/content/TextContent.php b/includes/content/TextContent.php
index 048ac39..0f7a531 100644 (file)
--- a/includes/content/TextContent.php
+++ b/includes/content/TextContent.php
@@ -1,10 +1,7 @@
 <?php
-
 /**
  * Content object implementation for representing flat text.
  *
- * TextContent instances are immutable
- *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -27,12 +24,23 @@
  *
  * @author Daniel Kinzler
  */
+
+/**
+ * Content object implementation for representing flat text.
+ *
+ * TextContent instances are immutable
+ *
+ * @ingroup Content
+ */
 class TextContent extends AbstractContent {
 
        public function __construct( $text, $model_id = CONTENT_MODEL_TEXT ) {
                parent::__construct( $model_id );
 
                if ( $text === null || $text === false ) {
+                       wfWarn( "TextContent constructed with \$text = " . var_export( $text, true ) . "! "
+                                       . "This may indicate an error in the caller's scope." );
+
                        $text = '';
                }
 
@@ -112,12 +120,21 @@ class TextContent extends AbstractContent {
        }
 
        /**
-        * Returns the text represented by this Content object, as a string.
+        * Returns attempts to convert this content object to wikitext,
+        * and then returns the text string. The conversion may be lossy.
         *
-        * @return string: the raw text
+        * @note: this allows any text-based content to be transcluded as if it was wikitext.
+        *
+        * @return string|false: the raw text, or null if the conversion failed
         */
        public function getWikitextForTransclusion( ) {
-               return $this->getNativeData();
+               $wikitext = $this->convert( CONTENT_MODEL_WIKITEXT, 'lossy' );
+
+               if ( $wikitext ) {
+                       return $wikitext->getNativeData();
+               } else {
+                       return false;
+               }
        }
 
        /**
@@ -234,4 +251,35 @@ class TextContent extends AbstractContent {
                # TODO: make Highlighter interface, use highlighter here, if available
                return htmlspecialchars( $this->getNativeData() );
        }
+
+       /**
+        * @see Content::convert()
+        *
+        * This implementation provides lossless conversion between content models based
+        * on TextContent.
+        *
+        * @param String  $toModel the desired content model, use the CONTENT_MODEL_XXX flags.
+        * @param String  $lossy flag, set to "lossy" to allow lossy conversion. If lossy conversion is
+        * not allowed, full round-trip conversion is expected to work without losing information.
+        *
+        * @return Content|bool A content object with the content model $toModel, or false if
+        * that conversion is not supported.
+        */
+       public function convert( $toModel, $lossy = '' ) {
+               $converted = parent::convert( $toModel, $lossy );
+
+               if ( $converted !== false ) {
+                       return $converted;
+               }
+
+               $toHandler = ContentHandler::getForModelID( $toModel );
+
+               if ( $toHandler instanceof TextContentHandler ) {
+                       //NOTE: ignore content serialization format - it's just text anyway.
+                       $text = $this->getNativeData();
+                       $converted = $toHandler->unserializeContent( $text );
+               }
+
+               return $converted;
+       }
 }