The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
GFUJI / HTML-FillInForm-Lite-1.10 / lib / HTML / FillInForm / Lite / JA.pod 

=encoding utf-8

=head1 NAME

HTML::FillInForm::Lite::JA - HTMLフォームにデータを充填する

=head1 VERSION

The document describes HTML::FillInForm::Lite version 1.10

=head1 SYNOPSIS

	use HTML::FillInForm::Lite;
	use CGI;

	my $q = CGI->new();
	my $h = HTML::FillInForm::Lite->new();

	$output = $h->fill(\$html,    $q);
	$output = $h->fill(\@html,    \%data);
	$output = $h->fill(\*HTML,    \&my_param);
	$output = $h->fill('t.html', [$q, \%default]);

	$output = $h->fill(\$html, $q,
		fill_password => 0, # it is default
		ignore_fields => ['foo', 'bar'],
		target        => $form_id,
	);

	# Moreover, it accept any object as data
	# (these classes come form Class::DBI's SYNOPSIS)

	my $artist = Music::Artist->insert({ id => 1, name => 'U2' });
	$output = $h->fill(\$html, $artist);

	my $cd = Music::CD->retrieve(1);
	$output = $h->fill(\$html, $cd);


=head1 DESCRIPTION

このモジュールはHTMLのフォームにデータを充填します。
これはC<HTML::FillInForm>をPure Perlで再実装したものです。

C<HTML::FillInForm>はC<HTML::Parser>によって実装されていますが、
このモジュールは正規表現ベースで実装されています。
その結果、C<HTML::FillInForm::Lite>はC<HTML::FillInForm>より最大で2倍ほど
高速に動作します。

=head1 METHODS

=head2 new(options...)

C<HTML::FillInForm::Lite>のインスタンスを作成します。

受け付けるオプションは以下の通りです。
オプションに未定義値を渡すと、そのオプションそのものを無視します。

=over 4

=item fill_password => I<bool>

このオプションを真に設定すると、パスワードも充填されるようになります。

このパスワードの効果はC<HTML::FillInForm>と同じですが、
このオプションを指定しなければ、C<HTML::FillInForm::Lite>は
パスワードフィールドを無視します。

=item ignore_fields => I<array_ref_of_fields>

指定したフォームフィールドを無視するようにします。

=item target => I<form_id>

I<form_id>をもつフォームのみを処理対象にします。

=item escape => I<bool> | I<ref>

オプションを指定しないか、C<1>(真)を指定した場合、テキストフィールドに充填される
値はHTMLエスケープされます。

すでに値がHTMLエスケープされている場合は、C<0>(偽)を指定してください。

サブルーチンリファレンスを指定すると、値のエスケープにそのサブルーチンを使います。

このオプションはC<HTML::FillInForm>には存在しません。

=item decode_entity => I<bool> | I<ref>

このオプションにC<1>(真)を指定した場合、状態を持つフィールド
（つまり、radio/checkbox/select）の値にあるHTML実体参照がデコードされます。
しかし，通常はこのオプションは必要ありません。

サブルーチンリファレンスを指定すると、実体参照のデコードに
そのサブルーチンを使います。

C<HTML::FillInForm>は自動的に状態フィールドのHTML実体参照をデコードしますが，
このオプションそれ自体は存在しません。

=item layer => I<:iolayer>

ファイルを読み込むときにI<:iolayer>を指定するようにします。
これはソースとしてファイル名が渡されたときに使われます。

使用例：

	# UTF-8でエンコードされたファイルを読むとき
	$fif = HTML::FillInForm::Lite->new(layer => ':utf8');
	$output = $fif->fill($file, $fdat);

	# EUC-JPでエンコードされたファイルを読むとき
	$fif = HTML::FillInForm::Lite->new(layer => ':encoding(euc-jp)');
	$output = $fif->fill($file, $fdat);


=back

=head2 fill(source, form_data [, options...])

I<souce>をI<form_data>で充填します。I<souce>またはI<form_data>が渡されない場合、C<die>します。

オプションはC<new()>と同じです。

このメソッドはクラスメソッドとしてもインスタンスメソッドとしても
呼び出せます。

C<fill()>をB<同じ>I<options>で何度も呼び出す場合は、
C<fill()>の前にあらかじめC<new()>でインスタンスを作っておくと少し高速になります。
しかし、同じインスタンスにつき一度しか呼び出さないなら、インスタンスを作った
としてもパフォーマンスは上がりません。

I<sorce>としては，スカラーリファレンスか文字列の配列リファレンス，
ファイル名，ファイルハンドルを渡すことが出来ます。

I<form_data>としては，ハッシュリファレンスかC<param()>メソッドを持つ
オブジェクト，アクセサを持つ任意のオブジェクト，前述のいずれかからなる
配列リファレンスを渡すことが出来ます。

I<form_data>がオブジェクトであれば，そのメソッドはリストコンテキストで呼ばれます。したがって，フィールドに手を付けたくない場合，C<undef>ではなく空リストC<()>を返さなければいけません。

=head1 DEPENDENCIES

Perl 5.8.1以上

=head1 NOTES

=head2 C<HTML::FillInForm>との互換性

このモジュールはC<HTML::FillInForm>バージョン2の新しい構文のみ実装しています。

C<HTML::FillInForm::Lite::Compat>はC<HTML::FillInForm>バージョン1の構文をサポートし，
オプションのデフォルト値もC<HTML::FillInForm>と同じになっています。

=head2 古いHTMLとの互換性

このモジュールはXHTML1.xを処理するように設計されています。
HTML4.xの大部分もサポートはしていますが、一部制限があります。

まず、HTML4では許されている属性名の省略はできません。

たとえば:

	<INPUT TYPE=checkbox NAME=foo CHECKED> - NG.
	<INPUT TYPE=checkbox NAME=foo CHECKED=CHECKED> - OK, ただし古い書き方
	<input type="checkbox" name="foo" checked="checked" /> - OK, 正しいXHTML

さらに、このモジュールは常に属性値の大文字・小文字を区別します。
上記の例では、C<type>属性の値は小文字でなければなりません。

さらに、閉じタグは省略できません。たとえば以下のようなコードは単に無視します。

	<select name="foo">
		<option>bar
		<option>baz
	</select>

正しいXHTMLで書けばこれらの問題は起こりません。

=head2 コメントの扱い

C<HTML::FillInForm::Lite>はコメントやその他の無視すべきものを理解しないので、
処理できるものは全て処理します。

このことが問題になることがあります。たとえば以下のコード:

	<script> document.write("<input name='foo' />") </script>

これは次のような誤ったコードに置換されます:

	<script> document.write("<input name='foo' value="bar" />") </script>

このような問題を避けるためにC<ignore_fields>オプションが使えます。

=head1 BUGS

No bugs have been reported.

Please report any bug or feature request to E<lt>gfuji(at)cpan.orgE<gt>,
or through thr RT L<http://rt.cpan.org/>.

=head1 SEE ALSO

L<HTML::FillInForm>.

L<HTML::FillInForm::Lite>.

L<HTML::FillInForm::Lite::Compat>.

=head1 AUTHOR

Goro Fuji (藤 吾郎) E<lt>gfuji(at)cpan.orgE<gt>

=head1 LICENSE AND COPYRIGHT

Copyright (c) 2008-2010 Goro Fuji, Some rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut