#?SuikaWiki/0.9
* SuikaWiki/0.9 での WikiForm の書き方

[1] [[SuikaWiki/0.9]]
([[SuikaWiki2]] の標準記述書式)
で [[WikiForm]] を使うためには、
-[SAMP[ [ [ # f o r m : ' [VAR[(入力雛形)]] ' : ' [VAR[(出力雛形)]] ' ] ] ]]
-[SAMP[ [ [ # f o r m : ' [VAR[(入力雛形)]] ' : ' [VAR[(出力雛形)]] ' : ' [VAR[(特性)]] ' ] ] ]]
-[SAMP[ [ [ # f o r m ( [VAR[(識別子)]] ) : ' [VAR[(入力雛形)]] ' : ' [VAR[(出力雛形)]] ' ] ] ]]
-[SAMP[ [ [ # f o r m ( [VAR[(識別子)]] ) : ' [VAR[(入力雛形)]] ' : ' [VAR[(出力雛形)]] ' : ' [VAR[(特性)]] ' ] ] ]]

の4つの書き方から1つ選びます。
普通は一番簡単な最初の形式でいいでしょう。

[3] 入力雛形・出力雛形・特性は、
[[Message::Util::Formatter]] の書式で記述します。
この書式は、簡単にいえば、
「普通」の文字列の中に、「%」
で始まる特別な意味を持たせた文字列を埋め込んだ物です。

例えば、
-[SAMP[%text (label => {お米}, id => rice); 合, %text (label => {パン}, id => bread); 枚]]
-[SAMP[お米を %text (source => rice); 合, パンを %text (source => bread); 枚用意すること。]]

のように記述します。
なお、 [CODE[%]] 自身を記述したい時は、
[CODE[%percent;]] とします。

[[#comment]]

* 入力雛形

[2] [DFN[入力雛形]]は、
入力を受け付ける欄の構成を
Message::Util::Formatter の書式で記述します。

例:
-[SAMP[%text (label => {お米}, id => rice); 合, %text (label => {パン}, id => bread); 枚]]

% で始まる部分 ([DFN[規則]]) は、適当な入力欄に置きかえられます。

短めの文字列を入力する
[CODE[%text;]]
の他にも、幾つかの種類が用意されています。

[4] 
: [CODE[%text;]] : 短めの文字列入力
: [CODE[%textarea;]] : 長めの文字列入力
: [CODE[%check;]] : チェック (入/切スイッチ)
: [CODE[%submit;]] : 送信ボタン

実際には他にもまだまだあります。
追加の [[WikiPlugin]] module
で拡張された物を使うことも出来ます。
現在使用出来るものの一覧は、
[[Wiki//Plugin//Info]] を見て下さい。
「form-input」に分類されているものを使えます。

[5] >>2 の例のように、規則には[DFN[引数]]を指定できます。
引数を使うときめ細かい制御ができます。
(中には必須の引数もあります。)

使用出来る引数は、規則により異なります。
同じ名前の引数でも、規則によって使われ方が異なることもありますから、注意して下さい。

主な引数:
: [CODE[id]] : 欄の識別子。
この識別子が入力雛形から作られた入力欄と出力雛形で使う入力結果を結び付けます。
識別子は、英語の[[ラテン文字]]で始まり、英数字や [CODE[-]] を使うことが出来ます。大文字・小文字は区別されます。
: [CODE[default]] : 既定値。
文字列入力では、初期状態がこの文字列の入った状態となります。
: [CODE[label]] : ラベル。その入力欄に何を入れるべきかを簡潔に記述します。例えば、名前記述欄では [SAMP[label => {名前}]] とするとよいでしょう。
: [CODE[description]] : 説明。その入力欄に何を入れるべきか、どう使われるかなどの説明を、程々の分量で記述します。
例えば、[SAMP[description => {この欄にあなたのお名前を書き込んで下さい。筆名で結構です。匿名希望の方は、空欄にして下さい。}]]
とか。
: [CODE[size]] : 文字数のヒント。
大体何文字くらい入力するかの目安を指定できます。最小・最大文字数の指定では''ない''ことに注意してください。
: [CODE[lines]] : 行数のヒント。
大体何行くらい入力するかの目安を指定できます。最小・最大行数の指定では''ない''ことに注意して下さい。

[[SuikaWiki3]] では、使用出来る引数の一覧も [[Wiki//Plugin//Info]]
でみることができます。

[[#comment]]

* 出力雛形

[6] 入力雛形から作られた入力欄に、
誰かが何かを入力し、送信したとします。
[DFN[出力雛形]]は、入力結果をどう処理するかの雛形として使われます。

出力雛形も、入力雛形と同じく、
Message::Util::Formatter
の書式を使いますが、
その生成結果は SuikaWiki/0.9
の書式とみなされます。

例えば、
-[SAMP[お米を ' ' ' %text (source => rice); 合' ' ', パンを ' ' ' %text (source => bread); 枚' ' ' 用意すること。]]

という出力雛形があるとします。
まず、入力結果が置きかえられます。
-[SAMP[お米を ' ' ' 2 合' ' ', パンを ' ' ' 3 枚' ' ' 用意すること。]]

のようになります。次にこれが
SuikaWiki/0.9 として処理されることになるので、
[SAMP[2 合]]と[SAMP[3 枚]]の部分が強調されることとなるのです。

[7] 出力雛形で使うことの出来る主な規則:
: [CODE[%text;]] : 入力された文字列に置きかえられます。
どの文字列かを、 [SAMP[%text (source => {foo});]] のように引数で指定しないといけません。ここで、 [VAR[foo]] には、入力雛形の [CODE[id]] 引数で指定した識別子を指定します。
: [CODE[%index;]] : 次の索引番号に置きかえられます。
索引番号とは、 SuikaWiki/0.9
書式中で「[」と「]」に挟まれた数字で、 >>1 のようにして参照されるもののことです。
: [CODE[%date;]] : その時点の日付と時刻に置きかえられます。

この他にも多くの規則があります。
一覧はやはり [[Wiki//Plugin//Info]]
で見ることが出来ます。「form-template」に分類されている物が該当します。

[[#comment]]

* 識別子

[8] >>1 の3番目と4番目の書式では、
括弧内に[DFN[識別子]]をつけることができます。
[WEAK[(この識別子と、入力雛形で使う [CODE[id]] 引数の識別子は関係ありません。)]]
この識別子は、その WikiForm
を識別する物で、その WikiPage
内で固有の物でなければなりません。
英語のラテン文字で始まり、
英数字と [CODE[-]] で構成します。
大文字・小文字が区別されます。

[9] この識別子と特性の出力先指定を組み合わせることで、
入力欄と離れた位置に結果を出力することが出来ます。

[[#comment]]

* 特性

[10] >>1 の2番目と4番目の書式では、
[DFN[特性]]を記述できます。
特性とは、 WikiForm の結果出力先の制御や入力必須指定などです。

特性の記述のためにも、やはり
Message::Util::Formatter
の書式を使います。[WEAK[ただし、入出力の雛形とは異なって、特性の記述はその文字列としての意味はありません。]]

例:
-[SAMP[%output (id => foo); %require (bread, rice);]]

[11] 特性で使える規則は、現在
2種類があります。
: [CODE[%output;]] : WikiForm の入力欄全体に関わる特性や、入力結果の処理主体を指定します。
: [CODE[%require;]] : 入力必須の欄の識別子を指定します。

弧の他に追加の規則が将来定義されるかもしれません。
[[Wiki//Plugin//Info]]
の分類「form-option」を確認して下さい。

[12] [CODE[%output;]] で指定できる主な引数:
: [CODE[form => [VAR[1 or 0]]]] : WikiForm標準の入力欄構成であるなら [CODE[1]] (既定値)、そうでないなら [CODE[0]] です。
この値を [CODE[0]] にすると、
これまでに説明したのよりもずっと柔軟な処理ができるようになりますが、
その分用意しなければならないことが増えます。 (ここでは詳しく説明しません。)
: [CODE[page => {[VAR[WikiName]]} : WikiForm の入力結果を処理する WikiPage を指定します。
普通は、この引数を指定した時には [CODE[id]] 引数も指定しないと行けません。
: [CODE[id => {[VAR[WikiForm ID]]} : WikiForm 入力結果を処理する WikiForm の識別子を指定します。
この引数が無ければ、同じ WikiForm
で処理します (ある入力雛形で作られた入力欄から入力された内容は、それとセットの出力雛形を使います)。
この引数を指定すると、その識別子の WikiForm の出力雛形などを使って処理します。
[CODE[page]] 引数が指定されているなら、その WikiPage 内で識別子を探します。
: [CODE[reverse]] : この引数が指定されていると、結果の出力を「逆順」に出力します。
通常の WikiForm の処理結果は、
その WikiForm の直前に挿入されます。
[WEAK[つまり、古い物から新しい物への順番になります。]]
この引数が指定されていると、
WikiForm の直後に挿入されます。
[WEAK[つまり、新しい物から古い物への順番になります。]]

[[#comment]]

* 使用例

[13] 百聞は一見に如かず、
ぜひ実例をごらんになってください。
有用な例が [[WikiFormCollection]]
に多々集められています。

まずは既存の WikiForm の不満な点があれば、それを修正することから始めてみてはどうでしょうか。

[[#comment]]

* メモ