SeamFramework.orgCommunity Documentation
Collaboration-oriented websites require a human-friendly markup language for easy entry
of formatted text in forum posts, wiki pages, blogs, comments, etc. Seam provides the
<s:formattedText/> control for display of formatted text that
conforms to the Seam Text language. Seam Text is implemented using
an ANTLR-based parser. You don't need to know anything about ANTLR to use it, however.
Here is a simple example:
It's easy to make *emphasis*, |monospace|, ~deleted text~, super^scripts^ or _underlines_.
If we display this using <s:formattedText/>, we will get
the following HTML produced:
<p>
It's easy to make <i>emphasis</i>, <tt>monospace</tt>
<del>deleted text</del>, super<sup>scripts</sup> or <u>underlines</u>.
</p>
We can use a blank line to indicate a new paragraph, and + to
indicate a heading:
+This is a big heading You /must/ have some text following a heading! ++This is a smaller heading This is the first paragraph. We can split it across multiple lines, but we must end it with a blank line. This is the second paragraph.
(Note that a simple newline is ignored, you need an additional blank line to wrap text into a new paragraph.) This is the HTML that results:
<h1>This is a big heading</h1>
<p>
You <i>must</i> have some text following a heading!
</p>
<h2>This is a smaller heading</h2>
<p>
This is the first paragraph. We can split it across multiple
lines, but we must end it with a blank line.
</p>
<p>
This is the second paragraph.
</p>
Ordered lists are created using the # character. Unordered lists
use the = character:
An ordered list:
#first item
#second item
#and even the /third/ item
An unordered list:
=an item
=another item<p>
An ordered list:
</p>
<ol>
<li>first item</li>
<li>second item</li>
<li>and even the <i>third</i> item</li>
</ol>
<p>
An unordered list:
</p>
<ul>
<li>an item</li>
<li>another item</li>
</ul>
Quoted sections should be surrounded in double quotes:
The other guy said:
"Nyeah nyeah-nee
/nyeah/ nyeah!"
But what do you think he means by "nyeah-nee"?<p>
The other guy said:
</p>
<q>Nyeah nyeah-nee
<i>nyeah</i> nyeah!</q>
<p>
But what do you think he means by <q>nyeah-nee</q>?
</p>
Special characters such as *, |
and #, along with HTML characters such as
<, > and &
may be escaped using \:
You can write down equations like 2\*3\=6 and HTML tags like \<body\> using the escape character: \\.
<p>
You can write down equations like 2*3=6 and HTML tags
like <body> using the escape character: \.
</p>
And we can quote code blocks using backticks:
My code doesn't work:
`for (int i=0; i<100; i--)
{
doSomething();
}`
Any ideas?<p>
My code doesn't work:
</p>
<pre>for (int i=0; i<100; i--)
{
doSomething();
}</pre>
<p>
Any ideas?
</p>
Note that inline monospace formatting always escapes (most monospace formatted text is in fact code or tags with many special characters). So you can, for example, write:
This is a |<tag attribute="value"/>| example.
without escaping any of the characters inside the monospace bars. The downside is that you can't format inline monospace text in any other way (italics, underscore, and so on).
A link may be created using the following syntax:
Go to the Seam website at [=>http://jboss.com/products/seam].
Or, if you want to specify the text of the link:
Go to [the Seam website=>http://jboss.com/products/seam].
For advanced users, it is even possible to customize the Seam Text parser to understand wikiword links written using this syntax.
Text may even include a certain limited subset of HTML (don't worry, the subset is chosen to be safe from cross-site scripting attacks). This is useful for creating links:
You might want to link to <a href="http://jboss.com/products/seam">something
cool</a>, or even include an image: <img src="/logo.jpg"/>
And for creating tables:
<table>
<tr><td>First name:</td><td>Gavin</td></tr>
<tr><td>Last name:</td><td>King</td></tr>
</table>
But you can do much more if you want!
The <s:formattedText/> JSF component internally uses the
org.jboss.seam.text.SeamTextParser. 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.
The following example defines a custom text parser that overrides the default HTML sanitizer:
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();
}
}
The linkTag() and paragraphOpenTag() methods are just some of many
you can override to customize rendered output. These methods generally return String.
See the Javadoc for more details.
Also consult the Javadoc of org.jboss.seam.text.SeamTextParser.DefaultSanitizer for
more information on what HTML elements, attributes, and attribute values or filtered by default.