[XPathBridge] add option to skip htmlspecialchars (#3672)

3 files changed, 51 insertions, 7 deletions

diff --git a/bridges/XPathBridge.php b/bridges/XPathBridge.php
index 52346aac..35ec6ad1 100644
--- a/bridges/XPathBridge.php
+++ b/bridges/XPathBridge.php
@@ -59,6 +59,17 @@ EOL, 'type' => 'text',
                 'required' => false
             ],
 
+            'raw_content' => [
+                'name' => 'Use raw item description',
+                'title' => <<<"EOL"
+                Whether to use the raw item description or to replace certain characters with
+                special significance in HTML by HTML entities (using the PHP function htmlspecialchars).
+                EOL,
+                'type' => 'checkbox',
+                'defaultValue' => false,
+                'required' => false
+            ],
+
             'uri' => [
                 'name' => 'Item URL selector',
                 'title' => <<<"EOL"
@@ -179,6 +190,15 @@ EOL, 'type' => 'checkbox',
     }
 
     /**
+     * Use raw item content
+     * @return bool
+     */
+    protected function getSettingUseRawItemContent(): bool
+    {
+        return $this->getInput('raw_content');
+    }
+
+    /**
      * XPath expression for extracting an item link from the item context
      * @return string
      */
@@ -226,9 +246,9 @@ EOL, 'type' => 'checkbox',
 
     /**
      * Fix encoding
-     * @return string
+     * @return bool
      */
-    protected function getSettingFixEncoding()
+    protected function getSettingFixEncoding(): bool
     {
         return $this->getInput('fix_encoding');
     }
diff --git a/docs/05_Bridge_API/04_XPathAbstract.md b/docs/05_Bridge_API/04_XPathAbstract.md
index cf091edc..fd697995 100644
--- a/docs/05_Bridge_API/04_XPathAbstract.md
+++ b/docs/05_Bridge_API/04_XPathAbstract.md
@@ -68,6 +68,9 @@ Should return the XPath expression for extracting an item title from the item co
 ### Method `getExpressionItemContent()`
 Should return the XPath expression for extracting an item's content from the item context.
 
+### Method `getSettingUseRawItemContent()`
+Should return the 'Use raw item content' setting value (bool true or false).
+
 ### Method `getExpressionItemUri()`
 Should return the XPath expression for extracting an item link from the item context.
 
diff --git a/lib/XPathAbstract.php b/lib/XPathAbstract.php
index 05929322..bac3bfd7 100644
--- a/lib/XPathAbstract.php
+++ b/lib/XPathAbstract.php
@@ -77,6 +77,15 @@ abstract class XPathAbstract extends BridgeAbstract
     const XPATH_EXPRESSION_ITEM_CONTENT = '';
 
     /**
+     * Use raw item content
+     * Whether to use the raw item content or to replace certain characters with
+     * special significance in HTML by HTML entities (using the PHP function htmlspecialchars).
+     *
+     * Use {@see XPathAbstract::getSettingUseRawItemContent()} to read this parameter
+     */
+    const SETTING_USE_RAW_ITEM_CONTENT = false;
+
+    /**
      * XPath expression for extracting an item link from the item context
      * This expression should match a node's attribute containing the article URL
      * (usually the href attribute of an <a> tag). It should start with a dot
@@ -237,6 +246,15 @@ abstract class XPathAbstract extends BridgeAbstract
     }
 
     /**
+     * Use raw item content
+     * @return bool
+     */
+    protected function getSettingUseRawItemContent(): bool
+    {
+        return static::SETTING_USE_RAW_ITEM_CONTENT;
+    }
+
+    /**
      * XPath expression for extracting an item link from the item context
      * @return string
      */
@@ -284,9 +302,9 @@ abstract class XPathAbstract extends BridgeAbstract
 
     /**
      * Fix encoding
-     * @return string
+     * @return bool
      */
-    protected function getSettingFixEncoding()
+    protected function getSettingFixEncoding(): bool
     {
         return static::SETTING_FIX_ENCODING;
     }
@@ -313,6 +331,8 @@ abstract class XPathAbstract extends BridgeAbstract
                 return $this->getExpressionItemTitle();
             case 'content':
                 return $this->getExpressionItemContent();
+            case 'raw_content':
+                return $this->getSettingUseRawItemContent();
             case 'uri':
                 return $this->getExpressionItemUri();
             case 'author':
@@ -417,7 +437,8 @@ abstract class XPathAbstract extends BridgeAbstract
                     continue;
                 }
 
-                $value = $this->getItemValueOrNodeValue($typedResult, $param === 'content');
+                $isContent = $param === 'content';
+                $value = $this->getItemValueOrNodeValue($typedResult, $isContent, $isContent && !$this->getSettingUseRawItemContent());
                 $item->__set($param, $this->formatParamValue($param, $value));
             }
 
@@ -573,7 +594,7 @@ abstract class XPathAbstract extends BridgeAbstract
      * @param $typedResult
      * @return string
      */
-    protected function getItemValueOrNodeValue($typedResult, $returnXML = false)
+    protected function getItemValueOrNodeValue($typedResult, $returnXML = false, $escapeHtml = false)
     {
         if ($typedResult instanceof \DOMNodeList) {
             $item = $typedResult->item(0);
@@ -596,7 +617,7 @@ abstract class XPathAbstract extends BridgeAbstract
 
         $text = trim($text);
 
-        if ($returnXML) {
+        if ($escapeHtml) {
             return htmlspecialchars($text);
         }
         return $text;