10:51 a.m.
Author: christian.bauer(a)jboss.com
Date: 2009-07-07 11:51:11 -0400 (Tue, 07 Jul 2009)
New Revision: 11249
Modified:
branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Text.xml
branches/community/Seam_2_2/seam-text.g
Log:
JBSEAM-4221, documented SeamTextParser and XSS sanitizer
Modified: branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Text.xml
===================================================================
--- branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Text.xml 2009-07-07
13:27:47 UTC (rev 11248)
+++ branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Text.xml 2009-07-07
15:51:11 UTC (rev 11249)
@@ -226,4 +226,72 @@
</section>
-</chapter>
\ No newline at end of file
+ <section>
+ <title>Using the SeamTextParser</title>
+
+ <para>
+ The <literal><s:formattedText/></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/community/Seam_2_2/seam-text.g
===================================================================
--- branches/community/Seam_2_2/seam-text.g 2009-07-07 13:27:47 UTC (rev 11248)
+++ branches/community/Seam_2_2/seam-text.g 2009-07-07 15:51:11 UTC (rev 11249)
@@ -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 <form>, <input> 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 {