[seam-commits] Seam SVN: r11280 - in branches/enterprise/JBPAPP_5_0: doc/Seam_Reference_Guide/en-US and 1 other directory.

[seam-commits at lists.jboss.org]

Author: manaRH
Date: 2009-07-13 11:57:43 -0400 (Mon, 13 Jul 2009)
New Revision: 11280

Modified:
   branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml
   branches/enterprise/JBPAPP_5_0/seam-text.g
Log:
back ported JBSEAM-4221

Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml	2009-07-13 15:50:48 UTC (rev 11279)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml	2009-07-13 15:57:43 UTC (rev 11280)
@@ -226,4 +226,72 @@
          
     </section>
     
-</chapter>
\ No newline at end of file
+   <section>
+       <title>Using the SeamTextParser</title>
+
+       <para>
+           The <literal>&lt;s:formattedText/&gt;</literal> JSF component internally uses the
+           <literal>org.jboss.seam.text.SeamTextParser</literal>. You can use that class directly and implement
+           your own text parsing, rendering, or HTML sanitation procedure. This is especially useful if you have
+           a custom frontend for entering rich text, such as a Javascript-based HTML editor, and you want to validate
+           user input to protect your website against Cross-Site Scripting (XSS) attacks. Another usecase
+           are custom wiki text parsing and rendering engines.
+       </para>
+
+       <para>
+           The following example defines a custom text parser that overrides the default HTML sanitizer:
+       </para>
+
+       <programlisting role="JAVA"><![CDATA[public class MyTextParser extends SeamTextParser {
+
+    public MyTextParser(String myText) {
+        super(new SeamTextLexer(new StringReader(myText)));
+
+        setSanitizer(
+            new DefaultSanitizer() {
+                @Override
+                public void validateHtmlElement(Token element) throws SemanticException {
+                    // TODO: I want to validate HTML elements myself!
+                }
+            }
+        );
+    }
+
+    // Customizes rendering of Seam text links such as [Some Text=>http://example.com]
+    @Override
+    protected String linkTag(String descriptionText, String linkText) {
+        return "<a href=\"" + linkText + "\">My Custom Link: " + descriptionText + "</a>";
+    }
+
+    // Renders a <p> or equivalent tag
+    @Override
+    protected String paragraphOpenTag() {
+        return "<p class=\"myCustomStyle\">";
+    }
+
+    public void parse() throws ANTLRException {
+        startRule();
+    }
+    
+}]]></programlisting>
+
+       <para>
+           The <literal>linkTag()</literal> and <literal>paragraphOpenTag()</literal> methods are just some of many
+           you can override to customize rendered output. These methods generally return <literal>String</literal>.
+           See the Javadoc for more details.
+       </para>
+
+       <para>
+           Also consult the Javadoc of <literal>org.jboss.seam.text.SeamTextParser.DefaultSanitizer</literal> for
+           more information on what HTML elements, attributes, and attribute values or filtered by default.
+       </para>
+
+   </section>
+
+</chapter>
+
+
+<!--
+        <programlisting role="JAVA"><![CDATA[
+]]></programlisting>
+-->
\ No newline at end of file

Modified: branches/enterprise/JBPAPP_5_0/seam-text.g
===================================================================
--- branches/enterprise/JBPAPP_5_0/seam-text.g	2009-07-13 15:50:48 UTC (rev 11279)
+++ branches/enterprise/JBPAPP_5_0/seam-text.g	2009-07-13 15:57:43 UTC (rev 11280)
@@ -91,6 +91,7 @@
     /**
      * Implementation of the rules in http://wiki.whatwg.org/wiki/Sanitization_rules
      *
+     * <pre>
      * Changes and additions:
      *
      * 1. Expanded all -* wildcard values to their full CSS property name (e.g. border-*).
@@ -107,10 +108,10 @@
      *
      * 7. Not implemented filtering of CSS url() - it's an invalid value always.
      *
-     * 8. Removed all <form>, <input> and other form tags. Attackers might use them compromise "outer" forms when entering
-     *    markup in a textarea.
+     * 8. Removed all &lt;form&gt;, &lt;input&gt; and other form tags. Attackers might use them to compromise
+     *    "outer" forms when entering such markup in a textarea.
+     * </pre>
      *
-     *
      */
     public static class DefaultSanitizer implements SeamTextParser.Sanitizer {