フォーム処理

フォームを使う

フォームはコントローラ、フォーム、モデル、ユーザ定義関数(、設定ファイル)から使用することができます。現在のクラスからメソッドnewForm(string $name)loadForm(string $name)を呼び出してインスタンスを生成し、そのインスタンスから以下のようにメソッドを実行します。

<?
class ctrlXxx extends CZCtrl {

	public function actionYyy() {
		$this->newForm('form1')->メソッド();
	}

}
?>

インスタンスを保持するかどうかでnewForm()loadForm()を使い分けますが、通常はnewFormで結構です。コンストラクタに引数を渡す場合、newForm()loadForm()の第2以降の引数として指定します。

<?
class ctrlXxx extends CZCtrl {

	public function actionYyy($uid = NULL, $gid = NULL) {
		$this->newForm('form1', $uid, $gid)->メソッド();
			:
	}

}
?>

フォームのコンストラクタで引数を使用する例として以下のようなケースがあります。

<?
class formForm1 extends CZForm {

	public function _construct($uid, $gid) {
		$parts = array(
				:
			'type_id' => array(
				'type' => 'select',
				'head_value' => array('' => '↓'),
				'table' => $this->newModel('item_type', $uid)->getTable('item_type_id', 'item_type_name'),
				'caption' => '種別',
			),
				:
		);
		$this->setParts($parts);
	}

}
?>

以下、これまでの設定に基づいて具体的なフォーム処理を行うメソッド群です。

フォームの初期化

フォームに入力した値はセッション情報として記憶され、フォームページに戻った時に直前に入力した値が表示されるようになっています。しかし改めてフォーム画面を開いて新たな処理を行う場合はセッション情報として残っている古い入力値を破棄して初期化する必要があります。

CZForm::initValues(array $replace_values = array())
(セッションに残っている)過去にフォームに入力した値を破棄します。$replace_valuesを指定した場合はその値をフォームの初期値としてセットします。形式はフォームのキーを変数名、値を表示させておく初期値とするレコード形式の連想配列となります。指定しない場合、入力タグの設定で初期値default_valueが指定されている場合はその初期値を入れますが、そうでない場合は空欄となります。

新規登録時

レコードの新規登録フォームや検索フォームを表示する際には古い入力値を破棄して空欄もしくは設定による初期値を入れます。

<?
class ctrlXxx extends CZCtrl {

	public function registIndex() {
		// フォームの値を破棄して初期化
		$form = $this->newForm('form1')->initValues();
	}

}
?>

古い入力値をフォームに残しておきたい場合はこの限りではありません。

更新時

レコードの更新フォームを表示する際にはデータベースの現在(更新前)のレコードの値をフォームに入れておきます。CZModel::getRecord()などで取得した(詳細はレコードの取得(Read)を参照)レコードをCZForm::initValues()の引数として指定すると、その値を初期値としてフォームにセットします。

<?
class ctrlXxx extends CZCtrl {

	public function updateIndex($id) {
		// 現在のレコードを取得
		$rec = $this->newModel('Item')->getRecordById($id);
		// フォームの初期値としてレコードの値を入れて初期化
		$form = $this->newForm('form1')->initValues($rec);
	}

}
?>

入力タグ(入力画面)の自動生成

設定したフォームについて、入力タグをHTMLとして生成します。PCからのアクセスと携帯電話からのアクセスとを自動で振り分けてそれぞれで適切な(X)HTMLを生成します。

入力変数ごと個別に入力タグを出力する

キャプション、入力タグ、エラーメッセージがそれぞれ変数ごとに出力できるメソッドが用意されています。

CZForm::getEditTag(string $part_name)
指定した入力タグ名のタグを取得します。<input>タグや<textarea>のみを出力します。前後のラベルやキャプションは含まれません。エラーメッセージも表示する場合はCZForm::getErr($part_name)でメッセージを取得して挿入します。
CZForm::getFormDataArea(string $part_name)
指定した入力タグ名のタグと前後のラベルなどの文字列、エラーメッセージを取得します。キャプションは含まれません。

これらはアクションの中で呼び出してビューにセットする値に代入してもいいですし、ビューの中で直接呼び出して使用しても結構です。たとえば

コントローラ

<?
class ctrlXxx extends CZCtrl {

	public function updateIndex() {
		// フォームインスタンスの取得
		$form = $this->newForm('form1')
		// フォームインスタンスそのものをビュー変数とする
		$this->addViewVar('form', $form);
	}

}
?>

ビュー

<p>編集する内容を入力してください。</p>
<form action="<? this->_url('confirm', 'update') ?>" method="post">
	<table>
	<tr>
		<th>テキストボックス01</th>
		<td><?= $form->getTag('text01') ?><?= $form->getErr('text01') ?></td>
	</tr>
	<tr>
		<th>チェックボックス01</th>
		<td><?= $form->getFormDataArea('check01') ?></td>
	</tr>
	</table>
	<input type="submit" value="送信" />
</form>

指定したフォーム内の入力タグをすべて自動で出力する

設定したフォーム内のすべての変数のキャプション、入力タグ、エラーメッセージを自動でまとめて出力することも可能です。入力タグは携帯電話以外ではテーブル(<table>~</table>)やリスト(<dl>~</dl>)に囲まれた状態での出力となり、開発者は<form>タグと送信ボタンのみ記述すれば結構です。表示順はsetParts(array $parts)の引数配列の要素の定義順となります。

CZForm::getFormHtml()
すべての入力タグをまとめて整形済みのHTMLで取得します。フォームタグ(<form>~</form>)と送信ボタン(<input type="submit">)は開発者が用意します。

以下のように使用します。

コントローラ

<?
class ctrlXxx extends CZCtrl {

	public function updateIndex() {
		// フォームインスタンスの取得
		$form = $this->newForm('form1');
		// getFormHtml()の結果をビュー変数とする
		$this->addViewVar('html', $form->getFormHtml(), FALSE);
	}

}
?>

ビュー

<p>編集する内容を入力してください。</p>
<form action="<? this->_url('confirm', 'update') ?>" method="post">
	<?= $html ?>
	<input type="submit" value="登録する" />
</form>

入力タグを何で囲むか(<table>かリスト<dl>)は設定ファイル{(app_root), _common}/configs/Html.phpの設定に従います。

<?
class configHtml extends CZConfig {

	public function _construct() {
		$this->setValues(array(
			'form' => array(
				'html_type'   => 'table',	// 'table' / 'dl' / 'br'
				'tag_options' => array(
					'table' => 'border="1" width="700"',
					'tr'    => '',
					'th'    => 'width="30%"',
					'td'    => 'width="70%"',
				),
				'caption_head_str' => '*',
				'caption_tail_str' => '',
			),
				:
		));
	}
}

?>

tag_typesformで表示形式を指定します。詳細は自動生成するHTMLに関する情報の設定も参照してください。

タグ生成機能を使わない

タグ生成機能を使わず、自分で入力タグをコーディングすることも可能です。開発者はビューに直接<input>タグを記述し、<select>の場合にはforeachなどを使ってループを回すことになります。その場合でもChimpanzeeはフォームの設定情報に基いてフォームからリクエストされた値を適切に受け取り、セッション情報として格納することができます。

<p>編集する内容を入力してください。</p>
<form action="<? this->_url('confirm', 'update') ?>" method="post">
	<table>
	<tr>
		<th>テキストボックス01</th>
		<td><input type="text" name="text01" id="text01" value="<?= $form_values['text01'] ?>" size="10" maxlength="15" />/td>
	</tr>
	<tr>
		<th>チェックボックス01</th>
		<td>
			<select name="select01" id="select01">
			<option value="">(以下から選択してください)</option>
 $val): ?>
			<option value=""></option>

			</select>
		</td>
	</tr>
	</table>
	<input type="submit" value="送信" />
</form>

フォームからの値の受取

フォームから受け取った値はセッション変数として自動的に適切な(他のセッション変数と重複しない)名前で保存されます。

入力値の受け取りとセッションへの保存

CZForm::saveValuesByPost()
当該フォームについてリクエストからすべての入力値を受け取りセッション情報に格納します。同時にバリデーションを行い、成功した場合にTRUEを、バリデーションに失敗した入力が1個でもあるとFALSEを返します。
リクエストから自動的に値を受け取り、設定どおりにセッション情報に格納するメソッドです。
<?
class ctrlXxx extends CZCtrl {

	public function registConfirm() {
		// 入力画面からの遷移以外は弾く
		$this->checkPrevActions(array(
			array('index'),
		));
		// フォームインスタンスの取得
		$form = $this->newForm('form1');

		// 入力値のセッションへの保存
		if (!$form->saveValuesByPost()) {
			// エラー処理;
			$this->_redirect(array('index'));
		}

		// 確認画面の表示(CZForm::getConfirmHtml()は後述)
		$this->addViewVar('confirm_html', $form->getConfirmHtml(), FALSE);
	}

}
?>
という使い方になります。
CZForm::saveValues(array $values)
指定した変数(入力タグ)と値の対をセッション情報に格納します。形式はキーを入力タグ名($part_name)、値を対応するタグの入力値とするレコード型の連想配列です。また実行と同時にバリデーションを行い、成功した場合にTRUEを、バリデーションに失敗した入力が1個でもあるとFALSEを返します。

saveValuesByPost()の後にsaveValues($values)を実行した場合、saveValuesByPost()で保存した内容はすべて上書きされます。したがってsaveValuesByPost()の実行後、saveValues($values)でフォームの中の一部の入力タグについてのみ値を指定して実行するとそれ以外の入力タグの入力値は消去されますので注意してください。

バリデーションエラーメッセージ

CZForm::getErr(string $part_name)
指定した入力タグ名のバリデーション(必須チェック、一致チェックを含む)時のエラーメッセージを取得します。エラーメッセージがセットされていない場合、空文字「''」を返します。
CZForm::saveErr($part_name, $msg)
指定した入力タグ名のバリデーション(必須チェック、一致チェックを含む)時のエラーメッセージを指定します。フォーム(クラス)の設定によるものを一時的に上書きすることができます。

セッション情報に格納された値を取得する

CZForm::saveValuesByPost()などでセッション情報に格納された値を取得して何らかの処理をすることも可能です。

CZForm::loadValues($default_values = array())
当該フォームについてセッション情報に格納されている入力値をCZForm::saveValues()の引数と同じレコード型の連想配列の形式で取得します。セッションに保存されていない場合、(デフォルト値として)$default_valuesで指定した内容を返します。引数$default_valuesの形式はキーを入力タグ名($part_name)、値を対応するタグの入力値とするレコード型の連想配列です。
<?
class ctrlXxx extends CZCtrl {

	public function registCommit() {

		// 入力画面からの遷移以外は弾く
		$this->checkPrevActions(array(
			array('index'),
		));

		// フォームインスタンスの取得
		$form = $this->newForm('form1');

		// 入力値をセッションへ格納
		if (!$form->saveValuesByPost()) {
			// エラー処理;
			$this->_redirect(array('index'));
		}

		// 入力値を取得
		$form_values = $form->loadValues();

		// 入力値をDBに保存
		if (!$this->newModel('model1')->commitInsert($form_values)) {
			// エラー処理;
			$this->_redirect(array('index'));
		}

		// フォームのクリア
		$form->freeAll();

		// 元のページに戻る
		$this->redirectReturn();

	}

}
?>

ファイルを受け取る場合

フォームからファイルを受け取る場合、CZForm::saveValuesByPost()実行時にアップロードされたファイルはフレームワークの一時ディレクトリ(tmp)に格納されます。必要に応じてこの一時ディレクトリ内のファイルに処理を加えてからファイルを保存しておく本ディレクトリに移動することになります。フレームワークが行うのは一時ディレクトリへの格納とファイル情報の取得までで、その後のファイル処理と移動については開発者がプログラムを書く必要があります。

CZForm::loadUploadedFiles()
アップロードされたファイルを一時ディレクトリに格納し、すべてのファイルについてのファイル情報を2次元配列で返します。配列の構造は
$uploaded_file_info = array(
	array(
		// ファイル1の情報
		'path'	=> 'アップロードされた一時ディレクトリ内のファイルのフルパス',
		'name'	=> 'ファイル名',
		'type'	=> 'ファイルの種類',
		'size'	=> 'ファイルサイズ',
	),
	array(
		// ファイル2の情報
		:
	), 
		:
)
となります。

一つのフォーム内で複数のファイルをアップロードする場合もあるので2次元配列となっています。ファイルが1つの場合、$uploaded_file_info[0]の配列を呼び出して使用することになります。

<?
class ctrlXxx extends CZCtrl {

	public function uploadCommit() {
		// 入力画面からの遷移以外は弾く
		$this->checkPrevActions(array(
			array('index'),
		));

		// フォームインスタンスの取得
		$form = $this->newForm('form1');

		// 入力値をセッションへ格納
		if (!$form->saveValuesByPost()) {
			$this->_redirect(array('index'));
		}

		// 入力値を取得
		$form_values = $form->loadValues();
		// ファイル情報を取得
		$uploaded_file_info = $form->loadUploadedFiles();

		// ファイルの格納パスを含めてDBに保存
		$add_values = array(
			'filepath' => '/path/to/filedir' . $uploaded_file_info[0]['name']
		);
		if (!$this->newModel('model1')->commitInsert($form_values, $add_values)) {
			$this->_redirect(array('index'));
		}

		// ファイルを本ディレクトリに移動
		move_uploaded_file($uploaded_file_info[0]['path'], '/path/to/filedir')

		// フォームのクリア
		$form->freeAll();

		// 元のページに戻る
		$this->redirectReturn();
	}

}
?>

CZForm::loadValues()と同様、あらかじめCZForm::saveValuesByPost()を実行しておく必要があることに気を付けてください。

確認画面処理

データベースのレコード操作を伴うフォーム処理では確認画面を表示することもあります。確認画面処理は通常、以下の流れになります。

フォームから入力された値をセッション情報に格納(値の一時保存) ▼ 入力値を取得してビューに挿入して表示(確認画面の表示) ▼ クライアントからの確認リクエストを受取 ▼ コミット処理...モデルなど

確認画面の表示(入力変数ごと個別に入力タグを出力)

確認画面で表示する確認用の値はフォームの入力値そのままでは不都合なこともあります。たとえば都道府県をプルダウンメニューで選択して入力した場合、入力値は通常ID(<option>タグのvalue属性)となりますが、表示させたいのは都道府県名です。また入力値に一定のルールに則った変換を加えて表示することもあります。確認画面表示メソッドではこのような処理済みの値を取得します。変換に関する設定はフォームの設定convertで指定できます。

CZForm::getConfirmDataArea(string $part_name, $escape_flag = TRUE)
指定した入力タグ名の確認用の入力値を取得します。$escape_flagがTRUEもしくは指定しない場合、フォームの入力内容中に含まれるHTMLタグ要素はエスケープ処理して表示可能な文字列に置換します。FALSEの場合タグ要素をそのままタグとして表示します。

これらはアクションの中で呼び出してビューにセットする値に代入してもいいですし、ビューの中で直接呼び出して使用しても結構です。たとえば

コントローラ

<?
class ctrlXxx extends CZCtrl {

	public function updateConfirm() {
		// 入力画面からの遷移以外は弾く
		$this->checkPrevActions(array(
			array('index'),
		));

		// フォームインスタンスの取得
		$form = $this->newForm('form1');

		// フォームインスタンスそのものをビュー変数とする
		$this->addViewVar('form', $form);
	}

}
?>

ビュー

<p>以下の内容で登録します。よろしいですか?</p>
<table>
<tr>
	<th>テキストボックス01</th>
	<td><?= $form->getConfirmDataArea('text01') ?></td>
</tr>
<tr>
	<th>チェックボックス01</th>
	<td><?= $form->getConfirmDataArea('check01') ?></td>
</tr>
</table>
<a href="<?= $this->_url('commit', 'update') ?>">はい</a>
<a href="<?= $this->_url('index', 'update') ?>">いいえ</a>

確認画面の表示(すべての入力タグについて自動で全出力)

設定したフォーム内のすべての入力の項目名と入力値を自動でまとめて出力することも可能です。入力タグは携帯電話以外ではテーブル(<table>~</table>)やリスト(<dl>~</dl>)に囲まれた状態での出力となり、開発者は確認ボタンのみ記述すれば結構です。表示順はCZForm::setParts(array $parts)の引数配列の要素の定義順となります。

CZForm::getConfirmHtml($escape_flag = TRUE)
セッション情報に格納された入力値を反映した確認画面用のHTMLを取得します。$escape_flagがTRUEもしくは指定しない場合、フォームの入力内容中に含まれるHTMLタグ要素はエスケープ処理して表示可能な文字列に置換します。FALSEの場合タグ要素をそのままタグとして表示します。
ファイルをアップロードした場合、画像ファイルの場合は画像を、その他のファイルの場合はファイル名を表示します。

CZForm::getFormHtml()と同様にHTMLを出力するメソッドですので、ビューの中で直接呼び出して利用できます。

コントローラ

<?
class ctrlXxx extends CZCtrl {

	public function registConfirm() {
		// 入力画面からの遷移以外は弾く
		$this->checkPrevActions(array(
			array('index'),
		));
		// フォームインスタンスの取得
		$form = $this->newForm('form1');

		// 入力値のセッションへの保存
		if (!$form->saveValuesByPost()) {
			// エラー処理;
			$this->_redirect(array('index'));
		}

		// 確認画面の表示
		$this->addViewVar('confirm_html', $form->getConfirmHtml(), FALSE);
	}

}
?>

ビュー

<p>以下の内容で登録します。よろしいですか?</p>
<?= $confirm_html ?>
<a href="<?= $this->_url('commit', 'update') ?>">はい</a>
<a href="<?= $this->_url('index', 'update') ?>">いいえ</a>

確認画面の表示形式は設定ファイル{(app_root), _common}/configs/Html.phpの設定に従います。

<?
	public function _construct() {
		$this->setValues(array(
				:
			'confirm' => array(
				'html_type'   => 'table',
				'tag_options' => array(
					'table' => 'border="1" width="700"',
					'tr'    => '',
					'th'    => 'width="30%"',
					'td'    => 'width="70%"',
				),
				'caption_head_str' => '*',
				'caption_tail_str' => '',
			),
				:
		));
	}
}
?>

tag_typesconfirmで表示形式を指定します。詳細は自動生成するHTMLに関する情報の設定も参照してください。

確認内容の反映

確認画面で「OK」の場合、「OK」のリンク先のアクションでデータベースへの書き込み等の処理を行います。

コントローラ

class ctrlXxx extends CZCtrl {
	public function updateCommit() {

		// 確認画面からの遷移以外は弾く
		$this->checkPrevActions(array(
			array('confirm'),
		));

		// フォームの入力値の取得
		$form_values = $this->newForm('form1')->loadValues();

		// DBへの保存
		if (!$this->newModel('model1')->commitInsert($form_values)) {
			// エラー処理
			$this->_redirect(array('index'));
		}

	}
}

前後のページ

ページトップへ