#14548: Add optional HTML help to filter.module's HTML filter.

3 files changed, 198 insertions, 10 deletions

diff --git a/misc/drupal.css b/misc/drupal.css
index 2d6f79d37..bf1811885 100644
--- a/misc/drupal.css
+++ b/misc/drupal.css
@@ -405,6 +405,10 @@ img.screenshot {
 .search-results .search-info {
   font-size: 0.85em;
 }
+.tips table {
+  margin-top: 1em;
+  margin-bottom: 1em;
+}
 #tracker td.replies {
   text-align: center;
 }
diff --git a/modules/filter.module b/modules/filter.module
index ed7ee3a83..8b02aff96 100644
--- a/modules/filter.module
+++ b/modules/filter.module
@@ -54,13 +54,99 @@ function filter_help($section) {
  * Implementation of hook_filter_tips().
  */
 function filter_filter_tips($delta, $format, $long = false) {
+  global $base_url;
   switch ($delta) {
     case 0:
       switch (variable_get("filter_html_$format", FILTER_HTML_STRIP)) {
 
         case FILTER_HTML_STRIP:
           if ($allowed_html = variable_get("allowed_html_$format", '<a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>')) {
-            return t('Allowed HTML tags') .': '. htmlspecialchars($allowed_html);
+            switch ($long) {
+              case 0:
+                return t('Allowed HTML tags') .': '. drupal_specialchars($allowed_html);
+              case 1:
+                $output = '<p>'. t('Allowed HTML tags') .': '. drupal_specialchars($allowed_html) .'</p>';
+                if (!variable_get("filter_html_help_$format", 1)) {
+                  return $output;
+                }
+
+                $output .= t('<p>This site allows HTML content. While learning all of HTML may feel intimidating, learning how to use a very small number of the most basic HTML "tags" is very easy. This table provides examples for each tag that is enabled on this site.</p>
+<p>For more information see W3C\'s <a href="http://www.w3.org/TR/html/">HTML Specifications</a> or use your favorite search engine to find other sites that explain HTML.</p>');
+                $tips = array(
+                  'a' => array( t('Anchors are used to make links to other pages.'), '<a href="'. $base_url .'">'. variable_get('site_name', 'drupal') .'</a>'),
+                  'br' => array( t('By default line break tags are automatically added, so use this tag to add additional ones. Use of this tag is different because it is not used with an open/close pair like all the others. Use the extra " /" inside the tag to maintain XHTML 1.0 compatibility'), t('Text with <br />line break')),
+                  'p' => array( t('By default paragraph tags are automatically added, so use this tag to add additional ones.'), '<p>'. t('Paragraph one.') .'</p> <p>'. t('Paragraph two.') .'</p>'),
+                  'strong' => array( t('Strong'), '<strong>'. t('Strong'). '</strong>'),
+                  'em' => array( t('Emphasized'), '<em>'. t('Emphasized') .'</em>'),
+                  'cite' => array( t('Cited'), '<cite>'. t('Cited') .'</cite>'),
+                  'code' => array( t('Coded text used to show programming source code'), '<code>'. t('Coded') .'</code>'),
+                  'b' => array( t('Bolded'), '<b>'. t('Bolded') .'</b>'),
+                  'u' => array( t('Underlined'), '<u>'. t('Underlined') .'</u>'),
+                  'i' => array( t('Italicized'), '<i>'. t('Italicized') .'</i>'),
+                  'sup' => array( t('Superscripted'), t('<sup>Super</sup>scripted')),
+                  'sub' => array( t('Subscripted'), t('<sub>Sub</sub>scripted')),
+                  'pre' => array( t('Preformatted'), '<pre>'. t('Preformatted') .'</pre>'),
+                  'blockquote' => array( t('Block quoted'), '<blockquote>'. t('Block quoted') .'</blockquote>'),
+                  'q' => array( t('Quoted inline'), '<q>'. t('Quoted inline') .'</q>'),
+                  // Assumes and describes tr, td, th.
+                  'table' => array( t('Table'), '<table> <tr><th>'. t('Table header') .'</th></tr> <tr><td>'. t('Table cell') .'</td></tr> </table>'),
+                  'tr' => NULL, 'td' => NULL, 'th' => NULL,
+                  'del' => array( t('Deleted'), '<del>'. t('Deleted') .'</del>'),
+                  'ins' => array( t('Inserted'), '<ins>'. t('Inserted') .'</ins>'),
+                   // Assumes and describes li.
+                  'ol' => array( t('Ordered list - use the &lt;li&gt; to begin each list item'), '<ol> <li>'. t('First item') .'</li> <li>'. t('Second item') .'</li> </ol>'),
+                  'ul' => array( t('Unordered list - use the &lt;li&gt; to begin each list item'), '<ul> <li>'. t('First item') .'</li> <li>'. t('Second item') .'</li> </ul>'),
+                  'li' => NULL,
+                  // Assumes and describes dt and dd.
+                  'dl' => array( t('Definition lists are similar to other HTML lists. &lt;dl&gt; begins the definition list, &lt;dt&gt; begins the definition term and &lt;dd&gt; begins the definition description.'), '<dl> <dt>'. t('First term') .'</dt> <dd>'. t('First definition') .'</dd> <dt>'. t('Second term') .'</dt> <dd>'. t('Second definition') .'</dd> </dl>'),
+                  'dt' => NULL, 'dd' => NULL,
+                  'h1' => array( t('Header'), '<h1>'. t('Title') .'</h1>'),
+                  'h2' => array( t('Header'), '<h2>'. t('Subtitle') .'</h2>'),
+                  'h3' => array( t('Header'), '<h3>'. t('Subtitle three') .'</h3>'),
+                  'h4' => array( t('Header'), '<h4>'. t('Subtitle four') .'</h4>'),
+                  'h5' => array( t('Header'), '<h5>'. t('Subtitle five') .'</h5>'),
+                  'h6' => array( t('Header'), '<h6>'. t('Subtitle six') .'</h6>')
+                );
+                $header = array(t('Tag Description'), t('You Type'), t('You Get'));
+                preg_match_all('/<([a-z0-9]+)[^a-z0-9]/i', $allowed_html, $out);
+                foreach ($out[1] as $tag) {
+                  if (array_key_exists($tag, $tips)) {
+                    if ($tips[$tag]) {
+                      $rows[] = array(
+                        array('data' => $tips[$tag][0], 'class' => 'description'),
+                        array('data' => '<code>'. drupal_specialchars($tips[$tag][1]) .'</code>', 'class' => 'type'),
+                        array('data' => $tips[$tag][1], 'class' => 'get')
+                      );
+                    }
+                  }
+                  else {
+                    $rows[] = array(
+                      array('data' => t('No help provided for tag %tag.', array('%tag' => drupal_specialchars($tag))), 'class' => 'description', 'colspan' => 3),
+                    );
+                  }
+                }
+                $output .= theme('table', $header, $rows);
+
+                $output .= t('<p>Most unusual characters can be directly entered without any problems.</p>
+<p>If you do encounter problems, try using HTML character entities. A common example looks like &amp;amp; for an ampersand &amp; character. For a full list of entities see HTML\'s <a href="http://www.w3.org/TR/html4/sgml/entities.html">entities</a> page. Some of the available characters include:</p>');
+                $entities = array(
+                  array( t('Ampersand'), '&amp;'),
+                  array( t('Greater than'), '&gt;'),
+                  array( t('Less than'), '&lt;'),
+                  array( t('Quotation mark'), '&quot;'),
+                );
+                $header = array(t('Character Description'), t('You Type'), t('You Get'));
+                unset($rows);
+                foreach ($entities as $entity) {
+                  $rows[] = array(
+                    array('data' => $entity[0], 'class' => 'description'),
+                    array('data' => '<code>'. drupal_specialchars($entity[1]) .'</code>', 'class' => 'type'),
+                    array('data' => $entity[1], 'class' => 'get')
+                  );
+                }
+                $output .= theme('table', $header, $rows);
+                return $output;
+            }
           }
           else {
             return t('No HTML tags allowed');
@@ -100,8 +186,13 @@ function filter_filter_tips($delta, $format, $long = false) {
       }
 
     case 2:
-      return t('Lines and paragraphs break automatically.');
+      switch ($long) {
+        case 0:
+          return t('Lines and paragraphs break automatically.');
+        case 1:
+          return t('Lines and paragraphs are automatically recognized. The &lt;br /&gt; line break, &lt;p&gt; paragraph and &lt;/p&gt; close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.');
       break;
+      }
   }
 }
 
@@ -730,7 +821,7 @@ function theme_filter_tips($tips, $long = false, $extra = '') {
       }
 
       if ($tips) {
-      $output .= "<ul class=\"tips\">$tips</ul>";
+        $output .= "<ul class=\"tips\">$tips</ul>";
       }
 
       if ($multiple) {
@@ -811,6 +902,7 @@ function filter_filter($op, $delta = 0, $format = -1, $text = '') {
 function _filter_html_settings($format) {
   $group = form_radios(t('Filter HTML tags'), "filter_html_$format", variable_get("filter_html_$format", FILTER_HTML_STRIP), array(FILTER_HTML_STRIP => t('Strip tags'), FILTER_HTML_ESCAPE => t('Escape tags')), t('How to deal with HTML tags in user-contributed content. If set to "Strip tags", dangerous tags are removed (see below).  If set to "Escape tags", all HTML is escaped and presented as it was typed.'));
   $group .= form_textfield(t('Allowed HTML tags'), "allowed_html_$format", variable_get("allowed_html_$format", '<a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>'), 64, 255, t('If "Strip tags" is selected, optionally specify tags which should not be stripped. Javascript event attributes are always stripped.'));
+  $group .= form_checkbox(t('Display HTML help'), "filter_html_help_$format", 1, variable_get("filter_html_help_$format", 1), t('If enabled, Drupal will display some basic HTML help in the long filter tips.'));
   $group .= form_radios(t('HTML style attributes'), "filter_style_$format", variable_get("filter_style_$format", FILTER_STYLE_STRIP), array(FILTER_STYLE_ALLOW => t('Allowed'), FILTER_STYLE_STRIP => t('Removed')), t('If "Strip tags" is selected, you can choose whether "STYLE" attributes are allowed or removed from input.'));
   $output .= form_group(t('HTML filter'), $group);
 
@@ -832,7 +924,7 @@ function _filter_html($text, $format) {
 
   if (variable_get("filter_html_$format", FILTER_HTML_STRIP) == FILTER_HTML_ESCAPE) {
     // Escape HTML
-    $text = htmlspecialchars($text);
+    $text = drupal_specialchars($text);
   }
 
   return trim($text);
@@ -867,4 +959,4 @@ function _filter_autop($text) {
  * @} End of "Standard filters".
  */
 
-?>
\ No newline at end of file
+?>
diff --git a/modules/filter/filter.module b/modules/filter/filter.module
index ed7ee3a83..8b02aff96 100644
--- a/modules/filter/filter.module
+++ b/modules/filter/filter.module
@@ -54,13 +54,99 @@ function filter_help($section) {
  * Implementation of hook_filter_tips().
  */
 function filter_filter_tips($delta, $format, $long = false) {
+  global $base_url;
   switch ($delta) {
     case 0:
       switch (variable_get("filter_html_$format", FILTER_HTML_STRIP)) {
 
         case FILTER_HTML_STRIP:
           if ($allowed_html = variable_get("allowed_html_$format", '<a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>')) {
-            return t('Allowed HTML tags') .': '. htmlspecialchars($allowed_html);
+            switch ($long) {
+              case 0:
+                return t('Allowed HTML tags') .': '. drupal_specialchars($allowed_html);
+              case 1:
+                $output = '<p>'. t('Allowed HTML tags') .': '. drupal_specialchars($allowed_html) .'</p>';
+                if (!variable_get("filter_html_help_$format", 1)) {
+                  return $output;
+                }
+
+                $output .= t('<p>This site allows HTML content. While learning all of HTML may feel intimidating, learning how to use a very small number of the most basic HTML "tags" is very easy. This table provides examples for each tag that is enabled on this site.</p>
+<p>For more information see W3C\'s <a href="http://www.w3.org/TR/html/">HTML Specifications</a> or use your favorite search engine to find other sites that explain HTML.</p>');
+                $tips = array(
+                  'a' => array( t('Anchors are used to make links to other pages.'), '<a href="'. $base_url .'">'. variable_get('site_name', 'drupal') .'</a>'),
+                  'br' => array( t('By default line break tags are automatically added, so use this tag to add additional ones. Use of this tag is different because it is not used with an open/close pair like all the others. Use the extra " /" inside the tag to maintain XHTML 1.0 compatibility'), t('Text with <br />line break')),
+                  'p' => array( t('By default paragraph tags are automatically added, so use this tag to add additional ones.'), '<p>'. t('Paragraph one.') .'</p> <p>'. t('Paragraph two.') .'</p>'),
+                  'strong' => array( t('Strong'), '<strong>'. t('Strong'). '</strong>'),
+                  'em' => array( t('Emphasized'), '<em>'. t('Emphasized') .'</em>'),
+                  'cite' => array( t('Cited'), '<cite>'. t('Cited') .'</cite>'),
+                  'code' => array( t('Coded text used to show programming source code'), '<code>'. t('Coded') .'</code>'),
+                  'b' => array( t('Bolded'), '<b>'. t('Bolded') .'</b>'),
+                  'u' => array( t('Underlined'), '<u>'. t('Underlined') .'</u>'),
+                  'i' => array( t('Italicized'), '<i>'. t('Italicized') .'</i>'),
+                  'sup' => array( t('Superscripted'), t('<sup>Super</sup>scripted')),
+                  'sub' => array( t('Subscripted'), t('<sub>Sub</sub>scripted')),
+                  'pre' => array( t('Preformatted'), '<pre>'. t('Preformatted') .'</pre>'),
+                  'blockquote' => array( t('Block quoted'), '<blockquote>'. t('Block quoted') .'</blockquote>'),
+                  'q' => array( t('Quoted inline'), '<q>'. t('Quoted inline') .'</q>'),
+                  // Assumes and describes tr, td, th.
+                  'table' => array( t('Table'), '<table> <tr><th>'. t('Table header') .'</th></tr> <tr><td>'. t('Table cell') .'</td></tr> </table>'),
+                  'tr' => NULL, 'td' => NULL, 'th' => NULL,
+                  'del' => array( t('Deleted'), '<del>'. t('Deleted') .'</del>'),
+                  'ins' => array( t('Inserted'), '<ins>'. t('Inserted') .'</ins>'),
+                   // Assumes and describes li.
+                  'ol' => array( t('Ordered list - use the &lt;li&gt; to begin each list item'), '<ol> <li>'. t('First item') .'</li> <li>'. t('Second item') .'</li> </ol>'),
+                  'ul' => array( t('Unordered list - use the &lt;li&gt; to begin each list item'), '<ul> <li>'. t('First item') .'</li> <li>'. t('Second item') .'</li> </ul>'),
+                  'li' => NULL,
+                  // Assumes and describes dt and dd.
+                  'dl' => array( t('Definition lists are similar to other HTML lists. &lt;dl&gt; begins the definition list, &lt;dt&gt; begins the definition term and &lt;dd&gt; begins the definition description.'), '<dl> <dt>'. t('First term') .'</dt> <dd>'. t('First definition') .'</dd> <dt>'. t('Second term') .'</dt> <dd>'. t('Second definition') .'</dd> </dl>'),
+                  'dt' => NULL, 'dd' => NULL,
+                  'h1' => array( t('Header'), '<h1>'. t('Title') .'</h1>'),
+                  'h2' => array( t('Header'), '<h2>'. t('Subtitle') .'</h2>'),
+                  'h3' => array( t('Header'), '<h3>'. t('Subtitle three') .'</h3>'),
+                  'h4' => array( t('Header'), '<h4>'. t('Subtitle four') .'</h4>'),
+                  'h5' => array( t('Header'), '<h5>'. t('Subtitle five') .'</h5>'),
+                  'h6' => array( t('Header'), '<h6>'. t('Subtitle six') .'</h6>')
+                );
+                $header = array(t('Tag Description'), t('You Type'), t('You Get'));
+                preg_match_all('/<([a-z0-9]+)[^a-z0-9]/i', $allowed_html, $out);
+                foreach ($out[1] as $tag) {
+                  if (array_key_exists($tag, $tips)) {
+                    if ($tips[$tag]) {
+                      $rows[] = array(
+                        array('data' => $tips[$tag][0], 'class' => 'description'),
+                        array('data' => '<code>'. drupal_specialchars($tips[$tag][1]) .'</code>', 'class' => 'type'),
+                        array('data' => $tips[$tag][1], 'class' => 'get')
+                      );
+                    }
+                  }
+                  else {
+                    $rows[] = array(
+                      array('data' => t('No help provided for tag %tag.', array('%tag' => drupal_specialchars($tag))), 'class' => 'description', 'colspan' => 3),
+                    );
+                  }
+                }
+                $output .= theme('table', $header, $rows);
+
+                $output .= t('<p>Most unusual characters can be directly entered without any problems.</p>
+<p>If you do encounter problems, try using HTML character entities. A common example looks like &amp;amp; for an ampersand &amp; character. For a full list of entities see HTML\'s <a href="http://www.w3.org/TR/html4/sgml/entities.html">entities</a> page. Some of the available characters include:</p>');
+                $entities = array(
+                  array( t('Ampersand'), '&amp;'),
+                  array( t('Greater than'), '&gt;'),
+                  array( t('Less than'), '&lt;'),
+                  array( t('Quotation mark'), '&quot;'),
+                );
+                $header = array(t('Character Description'), t('You Type'), t('You Get'));
+                unset($rows);
+                foreach ($entities as $entity) {
+                  $rows[] = array(
+                    array('data' => $entity[0], 'class' => 'description'),
+                    array('data' => '<code>'. drupal_specialchars($entity[1]) .'</code>', 'class' => 'type'),
+                    array('data' => $entity[1], 'class' => 'get')
+                  );
+                }
+                $output .= theme('table', $header, $rows);
+                return $output;
+            }
           }
           else {
             return t('No HTML tags allowed');
@@ -100,8 +186,13 @@ function filter_filter_tips($delta, $format, $long = false) {
       }
 
     case 2:
-      return t('Lines and paragraphs break automatically.');
+      switch ($long) {
+        case 0:
+          return t('Lines and paragraphs break automatically.');
+        case 1:
+          return t('Lines and paragraphs are automatically recognized. The &lt;br /&gt; line break, &lt;p&gt; paragraph and &lt;/p&gt; close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.');
       break;
+      }
   }
 }
 
@@ -730,7 +821,7 @@ function theme_filter_tips($tips, $long = false, $extra = '') {
       }
 
       if ($tips) {
-      $output .= "<ul class=\"tips\">$tips</ul>";
+        $output .= "<ul class=\"tips\">$tips</ul>";
       }
 
       if ($multiple) {
@@ -811,6 +902,7 @@ function filter_filter($op, $delta = 0, $format = -1, $text = '') {
 function _filter_html_settings($format) {
   $group = form_radios(t('Filter HTML tags'), "filter_html_$format", variable_get("filter_html_$format", FILTER_HTML_STRIP), array(FILTER_HTML_STRIP => t('Strip tags'), FILTER_HTML_ESCAPE => t('Escape tags')), t('How to deal with HTML tags in user-contributed content. If set to "Strip tags", dangerous tags are removed (see below).  If set to "Escape tags", all HTML is escaped and presented as it was typed.'));
   $group .= form_textfield(t('Allowed HTML tags'), "allowed_html_$format", variable_get("allowed_html_$format", '<a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>'), 64, 255, t('If "Strip tags" is selected, optionally specify tags which should not be stripped. Javascript event attributes are always stripped.'));
+  $group .= form_checkbox(t('Display HTML help'), "filter_html_help_$format", 1, variable_get("filter_html_help_$format", 1), t('If enabled, Drupal will display some basic HTML help in the long filter tips.'));
   $group .= form_radios(t('HTML style attributes'), "filter_style_$format", variable_get("filter_style_$format", FILTER_STYLE_STRIP), array(FILTER_STYLE_ALLOW => t('Allowed'), FILTER_STYLE_STRIP => t('Removed')), t('If "Strip tags" is selected, you can choose whether "STYLE" attributes are allowed or removed from input.'));
   $output .= form_group(t('HTML filter'), $group);
 
@@ -832,7 +924,7 @@ function _filter_html($text, $format) {
 
   if (variable_get("filter_html_$format", FILTER_HTML_STRIP) == FILTER_HTML_ESCAPE) {
     // Escape HTML
-    $text = htmlspecialchars($text);
+    $text = drupal_specialchars($text);
   }
 
   return trim($text);
@@ -867,4 +959,4 @@ function _filter_autop($text) {
  * @} End of "Standard filters".
  */
 
-?>
\ No newline at end of file
+?>