SeamFramework.orgCommunity Documentation

第17章 Seam Text

17.1. フォーマットの基本
17.2. プログラムコードや特殊文字を含むテキストの記述
17.3. リンク
17.4. HTMLの記述
17.5. Using the SeamTextParser

多くの人が一緒に作業するウェブサイトでは、 フォーラムへの投稿、wikiページ、blog、コメントなどでフォーマット済みテキストを簡単に入力するために人間が扱いやすいマークアップ言語が必要になります。 Seamには Seam Text と呼ばれる言語に従ったフォーマット済みテキストを Web 表示するための仕組みがあって、 <s:formattedText/> によってそれを制御します。 Seam TextはANTLRベースのパーサを利用して実装されていますが、 Seam Textを利用するにあたってANTLRについての知識は不要なので安心してください。

シンプルな例:

It's easy to make *emphasis*, |monospace|,
~deleted text~, super^scripts^ or _underlines_.

これを <s:formattedText/> で表示させると、 以下のHTMLが生成されます:


<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
>

空行は新しいパラグラフを作成するときに使用します。 また、+ は見出しに使用します:

+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.

(段落内の改行は単に無視されます。 新しい段落としてテキストを記述したい場合は空行が必要なことを忘れないでください。) これが結果の HTML です:


<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
>

順序付きリストは # 文字で作成できます。順序なしリストは = 文字を使います:

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
>

引用ブロックはダブルクオートで囲む必要があります:

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
>

*, |, # などの特殊文字や、<, >, & などのHTMLで利用される文字は \ でエスケープします:

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 &lt;body&gt; using the escape character: \.
</p
>

また、 バックティック (`) を使ってコードのブロックを囲むことができます。

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&lt;100; i--)
{
    doSomething();
}</pre>

<p>
Any ideas?
</p
>

インライン固定スペースのフォーマットはいつもエスケープ処理されます (ほとんどの固定スペースフォーマットされたテキストは実際には特殊な文字のあるタグやコードになります)。 したがって、例えば以下のように固定スペースのバー内でいずれの文字もエスケープ処理することなく記述することができます。

This is a |<tag attribute="value"/>| example.

一方、 その他の方法ではインライン固定スペーステキストをフォーマット化することができません (斜字体、 下線など)。

リンクを作るには以下の構文を利用します:

Go to the Seam website at [=
>http://jboss.com/products/seam].

または、リンクテキストを指定したい場合:

Go to [the Seam website=
>http://jboss.com/products/seam].

上級者向けですが、この構文を利用したwikiワードのリンクを解釈できるようSeam Textパーサをカスタマイズすることも可能です。

テキストには限定されたHTMLのサブセットを含めることができます (心配しないでください、 クロスサイトスクリプティング攻撃には利用できないようなサブセットを選んでいます)。 これはリンクを作成する際などに便利です。


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"/>

テーブルも作れます:


<table>
    <tr
><td
>First name:</td
><td
>Gavin</td
></tr>
    <tr
><td
>Last name:</td
><td
>King</td
></tr>
</table
>

やろうと思えば他にもいろいろできるでしょう!

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.