複数レコードの取得

検索やページング、DISTINCTを用いたレコードの取得など、メソッドCZModel::getRecords()でできることを超えた複雑な複数レコードの取得に関するメソッドやそれらの挙動を制御する設定です。

設定

複数レコードの取得を行う場合、以下のようにモデルのコンストラクタでメソッドCZModel::_addRecords()を用いて取得に関する設定をします。

<?
class modelXxx extends CZModel {

	public function _construct() {
		// モデルの設定
		$this->setTable('item', 'item_id');
			:

		// 複数レコードの取得に関する設定
		$this->_addRecords()->setCaptions(array(
			'item_id'	=> 'ID',
			'item_name' => '商品名',
			'item_code' => '商品コード',
		));
	}

}
?>

設定は

$this->_addRecords()->設定メソッド(引数);

の形式で設定メソッドを用いて行います。内部的にはメソッドCZModel::_addRecords()を実行すると複数レコードの取得を制御するCZModelRecordsクラスのインスタンスが生成され、それに対して設定メソッドを用いて設定を行っていく（プロパティを付与していく）仕組みになります。

CZModel::_addRecords($name = 'default'): 複数レコード取得インスタンスを生成します。引数$nameでインスタンス名を指定できますので、複数のインスタンスを生成することも可能です。$nameを指定しない場合、インスタンス名として「default」が適用されます。実行時、CZModelRecordsオブジェクトを返します。
インスタンスから取得するカラムやページングのルールなど取得に関するプロパティを設定します。複数のインスタンスを生成して取得に関する異なるルールを設定して使い分けることも可能です。
同一のCZModelRecordsインスタンスに対して_addRecords()を複数回実行するとエラーになります。したがって引数を省略して_addRecords()を2回実行するとエラーになりますので注意してください。

CZModel::_addRecords()に引き続いて実行する設定メソッドです。

setColumnNames(array $names)

複数レコード取得系メソッド（get()、getTable()、getListHtml()）で取得するカラム名を配列で指定します。引数$namesの形式はカラム名を要素とする配列

$names = array('column_name1', 'column_name2', 'column_name4');

のようになります。このメソッドを実行しない場合はすべてのカラムを取得することになります。このメソッドを実行した場合、引数に含まれないカラムは取得されません。getTable()の引数で指定したカラムがsetColumnNames(array $names)の引数に含まれない場合、エラーとなりますので注意してください。実行時、実行元インスタンスのオブジェクトを返します。

setCaptions(array $captions)

メソッドgetListHtml()で取得する一覧表示HTML内のカラムとそれに付けるキャプションを連想配列で指定します。setColumnNames(array $names)で指定したカラムに対してのみ有効となります。連想配列の形式は、キーが表示するカラム名、値がカラムに対応するキャプションの文字列

$captions = array(
	'column_name1' => 'カラム1のキャプション',
	'column_name2' => 'カラム2のキャプション',
		:
);

となります。変数は表示するがキャプションを表示しない場合、値に空文字「''」をセットします。

$captions = array(
	'column_name1' => '',
		:
);

このメソッドを実行しない場合はsetColumnNames(array $names)で指定したすべてのカラムが表示されますが、setCaptions(array $captions)を実行した場合にはカラム名とキャプションの組を設定していないとそのカラムは表示されません。実行時、実行元インスタンスのオブジェクトを返します。

enableLinkToDetail()

このメソッドを実行すると一覧表示HTMLの中に詳細ページへのリンクを挿入します。実行時、実行元インスタンスのオブジェクトを返します。

enableLinkToUpdate()

このメソッドを実行すると一覧表示HTMLの中に編集（変更）ページへのリンクを挿入します。実行時、実行元インスタンスのオブジェクトを返します。

enableLinkToDelete()

このメソッドを実行すると一覧表示HTMLの中に削除ページへのリンクを挿入します。実行時、実行元インスタンスのオブジェクトを返します。

設定メソッドは実行元インスタンスのオブジェクトを返しますので、メソッドチェインの形で設定を追加していくことができます。

<?
class modelXxx extends CZModel {

	public function _construct() {

			:
		$this->_addRecords()->setColumnNames(array(
			'item_id',
			'item_name',
			'item_code',
		))->setCaptions(array(
			'item_id'	=> 'ID',
			'item_name' => '商品名',
			'item_code' => '商品コード',
		));
	}

}
?>

一覧取得

上記のように設定した複数レコード取得（CZModelRecordsクラス）インスタンスから実際にレコードを取得します。

<?
class ctrlXxx extends CZCtrl {

	public function actionXxx() {
		$recs = $this->newModel('item')->_getRecords()->get();
		$this->addViewVar('recs', $recs);
	}

}
?>

取得は

$model_obj->_getRecords()->取得メソッド(引数);

の形式で取得メソッドを用いて行います。メソッドCZModel::_addRecords()で生成したCZModelRecordsクラスのインスタンスから取得メソッド実行して複数レコードを取得する仕組みになります。

CZModel::_getRecords($name = 'default'): 指定したインスタンス名のCZModelRecordsオブジェクトを取得します。あらかじめメソッドCZModel::_addRecords($name)で設定済みのインスタンスについて（プロパティが設定された状態で）取得しますが、事前に設定していない場合は新たにCZModelRecordsクラスのインスタンスを生成して（プロパティが設定されていない状態で）取得します。この場合後述するメソッドget()を実行すると全カラム全レコードを取得することになります。

CZModel::_getRecords()に引き続いて実行するレコード取得メソッドです。

get($escape_flag = FALSE, array $ignore_escape_keys = NULL, $format_flag = TRUE): (returns array)複数のレコードをレコードセット型の2次元配列で取得します。
$escape_flagがTRUEの場合、値に含まれるHTMLタグ要素はエスケープ処理して表示可能な文字列に置換します。FALSEもしくは指定しない場合タグ要素はそのままタグとして取得されます。$ignore_escape_keysでエスケープ対象から除外するキーを指定することもできます。エスケープに関する指定の詳細はこちらも参照してください。
$format_flagがTRUEもしくは指定しない場合、CZModel::setFormats(array $formats)で指定したフォーマットを行って値を返します。FALSEの場合はフォーマットをしないままの値を返します。通常は指定しませんが（フォーマット済み）、ユーザ関連処理などでフォーマットされた値では都合が悪い場合にFALSEを指定します。
あらかじめCZModel::_addRecords()を用いて取得に関する設定をしていない場合、全カラム全レコードを取得することになりますので注意してください。
getTable(string $id_column_name, string $value_column_name, $format_flag = TRUE): (returns array)IDと指定したカラムの値の一覧を定数テーブル型の配列で取得します。$id_column_nameでIDのカラム名を、$value_column_nameで値のカラム名を文字列で指定します。特定のカラムを定数テーブルとして取得したい場合に利用します。$format_flagがTRUEもしくは指定しない場合、CZModel::setFormats(array $formats)で指定したフォーマットを行って値を返します。FALSEの場合はフォーマットをしないままの値を返します。通常は指定しませんが（フォーマット済み）、ユーザ関連処理などでフォーマットされた値では都合が悪い場合にFALSEを指定します。
getListHtml($escape_flag = TRUE, $ignore_escape_keys = NULL, $format_flag = TRUE): (returns string)一覧表のHTMLを取得します。引数については上記get($escape_flag = FALSE, array $ignore_escape_keys = NULL, $format_flag = TRUE)を参照してください。

検索やページング処理によって取得するレコードを絞り込むことができます。CZModel::_getRecords()で取得したインスタンスから絞り込みやページングのメソッドを実行します。

$model_obj->_getRecords()->絞り込み／ページングメソッド(引数);

setCondition(array $sentences, $values = array()): 取得するレコードの絞り込み条件（WHERE節）を指定します。条件の指定形式は検索条件の指定方法を参照してください。実行時、実行元インスタンスのオブジェクトを返します。
enableDistinct(): レコードの取得時「DISTINCT」を有効にします。DISTINCTの対象になるカラムは取得するカラムすなわちsetColumnNames($names)で指定したカラムとなります。
setGroupColumnNames(array $names): 「GROUP BY」で指定するカラムを配列で与えます。指定カラムの値でグループ化してレコードを取得します。指定しない場合グループ化しません。実行時、実行元インスタンスのオブジェクトを返します。
setHaving(array $condition_sentences, $condition_values = array()): 「HAVING」の内容を指定します。モデルの絞り込み条件の指定方法と同じ形式で指定をします。実行時、実行元インスタンスのオブジェクトを返します。
setOrderSentences($sentences): 「ORDER BY」で指定するカラムを配列で与えます。指定カラムの値の並び順でレコードを取得します。指定しない場合並び順はプライマリキーの並び順になります。実行時、実行元インスタンスのオブジェクトを返します。
setLimit(int $limit): 「LIMIT」で設定される取得レコード数を整数で指定します。指定しない場合、ページング処理の設定に従います。実行時、実行元インスタンスのオブジェクトを返します。
setOffset(int $offset): 「OFFSET」で設定される取得開始レコード数を整数で指定します。指定しない場合、ページング処理の設定に従います。実行時、実行元インスタンスのオブジェクトを返します。

これらのメソッドは実行元インスタンスのオブジェクトを返しますので、メソッドチェインの形で条件を指定していくこともできます。インスタンスに対して絞り込んだ後、取得メソッドを実行します。

<?
class ctrlXxx extends CZCtrl {

	public function actionXxx() {
		// インスタンスの生成
		$item_obj = $this->newModel('item')->_getRecords();

  		// 絞り込みとページング
		$item_obj->setCondition(
				array('item_name = :item_name'), 
				array('item_name'=> $item_name)
			)->setLimit(100)->setOffset(100);

		// 取得
		$recs = $item_obj->get();

		// 表示
		$this->addViewVar('recs', $recs);
	}

}
?>

設定したプロパティの取得

getModel(): 複数レコード取得処理をするモデルのオブジェクトを取得します。
getColumnNames(): 複数レコード取得系メソッドで取得するカラム名を配列で取得します。setColumnNames($names)で指定した$namesと同じになります。
getConditionSentences(): 取得するレコードの絞り込み条件（WHERE節）を配列で取得します。setCondition($sentences, $values = array())で指定した$sentencesと同じになります。
getConditionValues(): 取得するレコードの絞り込み条件（WHERE節）に代入する値（の組み合わせ）を配列で取得します。setCondition($sentences, $values = array())で指定した$valuesと同じになります。
getDistinctFlag(): レコードの取得時「DISTINCT」が有効な場合TRUEを、そうでない場合FALSEを返します。
getGroupColumnNames(): 「GROUP BY」で指定するカラムを配列で与えます。setGroupColumnNames($names)で指定した$namesと同じになります。
getOrderSentences(): 「ORDER BY」で指定するカラムを配列で取得します。setOrderSentences($sentences)で指定した$sentencesと同じになります。
getLimit(): 「LIMIT」で設定される取得レコード数を整数で取得します。setLimit($limit)で指定した$limitと同じになります。
getOffset(): 「OFFSET」で設定される取得開始レコード数を整数で取得します。setOffset($offset)で指定した$offsetと同じになります。
getCaptions(): 一覧表示HTML内のカラムとそれに付けるキャプションを連想配列で取得します。setCaptions($captions)で指定した$captionsと同じになります。
getLinkToDetailFlag(): 一覧表示HTMLの中に詳細ページへのリンクを挿入する場合TRUEを、しない場合FALSEを返します。
getLinkToUpdateFlag(): 一覧表示HTMLの中に編集（変更）ページへのリンクを挿入する場合TRUEを、しない場合FALSEを返します。
getLinkToDeleteFlag(): 一覧表示HTMLの中に削除ページへのリンクを挿入する場合TRUEを、しない場合FALSEを返します。

ページング

ページングに関するメソッド

レコードの一覧取得の場合、ページングが発生します。ページング処理においてはページ番号や1ページあたりの表示件数をリクエスト変数として受け取り、それに基づいてレコードを取得します。ChimpanzeeではモデルでenablePaging(int $default_row_num, $page_num_param_name = 'pn', $row_num_param_name = 'rn')を実行しておくことでそれらを自動で行い、適切なレコードを取得してくれます。またリクエスト変数を含んだ前後のページへのリンクのURLも適切に出力します。

enablePaging(int $default_row_num, $page_num_param_name = 'pn', $row_num_param_name = 'rn'): このメソッドを実行することで自動でページング処理が行われます。$default_row_numで1ページに表示する（一度に取得する）デフォルトのレコード数を指定します。またページングで使用するリクエスト変数名も指定できます。$page_num_param_nameでページ番号の、$row_num_param_nameで1ページのレコード数（ユーザが指定する場合）のURLリクエストパラメータ名を指定します。
$page_num_param_nameがURLに現れるのは2ページ目以降のみで、1ページ目の「?pn=1」はURLに表示されません（「?pn=1」の有無による複数URL同一コンテンツの発生を防ぐため）。

ページ情報の取得メソッドです。ビューの中で使用するページングのナビゲーションに用います。

getPrevPageUrl()

(returns string) 現在表示している1つ前のページのURLを取得します。

getNextPageUrl()

(returns string) 現在表示している1つ後のページのURLを取得します。

getCurrentPageNum()

(returns integer) 現在表示しているページのページ番号を取得します。

getMaxPageNum()

(returns integer) 最後のページ番号を取得します。

getPaging()

enablePaging(int $default_row_num, $page_num_param_name = 'pn', $row_num_param_name = 'rn')で設定した内容を連想配列で取得します。形式は

array(
	'default_row_num' => 20
	'page_num_param_name' => 'pn'
	'row_num_param_name' => 'rn'
);

となります。

ページングの実装

ページングの有効化

モデルで$this->_addRecords()からenablePaging()を実行するとページングを行います。

<?
class modelItem extends CZModel {

	public function _construct() {
			:
		$this->_addRecords()
			->setColumnNames(array(
				'item_id',
				'item_name',
			))
			->setOrderSentences(array(
				'sort_num',
				'item_id',
			))
			->enablePaging(10);
	}

}
?>

ページングリクエストの受け取りとレコード取得（アクション）

レコードやページ情報を取得し、ビュー変数にセットします。リクエスト変数に関する処理はフレームワークが自動で行うので記述不要です。

<?
class ctrlYyy extends CZCtrl {

	public function listIndex() {
		$records = $this->newModel('item')->_getRecords();

		// レコードの取得
		$items = $records->get();

		// ページング情報の取得
		$_prev_page_url = $records->getPrevPageUrl();
		$_next_page_url = $records->getNextPageUrl();
		
		// ビュー変数の設定
		$this->addViewVar('items', $items);
		$this->addViewVar('_prev_page_url', $_prev_page_url);
		$this->addViewVar('_next_page_url', $_next_page_url);
	}

}
?>

ページング情報の表示（ビュー）

上記のビュー変数からレコードやページ情報を表示します。

<? if($items): ?>
<table>
<? foreach($items as $item): ?>
<tr>
<td><?= $item['item_id'] ?></td>
<td><?= $item['item_name'] ?></td>
	:
</tr>
<? endforeach; ?>
</table>
<? else: ?>
<p>レコードがありません。</p>
<? endif; ?>
<? if ($_prev_page_url): ?><a href="<?= $_prev_page_url; ?>">前ページ</a><? endif; ?>
<? if ($_next_page_url): ?><a href="<?= $_next_page_url; ?>">次ページ</a><? endif; ?>

検索

検索に関するメソッド

setSearch(array $condition_sentences, $condition_values = array()): 表示レコードを絞り込む検索条件を指定します。指定方法は検索条件の指定方法を参照してください。
getSearchConditionSentences(): 取得するレコードの絞り込み条件（WHERE節）を配列で取得します。addSearch($condition_sentences, $condition_values = array())で指定した$condition_sentencesと同じになります。
getSearchConditionValues(): 取得するレコードの絞り込み条件（WHERE節）に代入する値（の組み合わせ）を配列で取得します。addSearch($condition_sentences, $condition_values = array())で指定した$condition_valuesと同じになります。

検索の実装

検索リクエストの受け取りとレコード取得（アクション）

リクエストに基づいて検索結果を取得し、検索フォームと一緒にビュー変数にセットします。

<?
class ctrlYyy extends CZCtrl {

	public function actionIndex() {
		$condition_sentences = array();
		$condition_values    = array();

		// リクエスト変数の受け取り処理
		$params = $this->newModule('request')->getGetParams();

		// 検索条件の指定
		if (isset($params['item_id']) && $params['item_id']) {
			$condition_sentences[] = 'item_id = :item_id';
			$condition_values['item_id'] = $params['item_id'];
		}
		if (isset($params['client_id']) && $params['client_id']) {
			$condition_sentences[] = 'client_id = :client_id';
			$condition_values['client_id'] = $params['client_id'];
		}
		if (isset($params['sex_id']) && $params['sex_id']) {
			$condition_sentences[] = 'sex_id = :sex_id';
			$condition_values['sex_id'] = $params['sex_id'];
		}
		
		// 検索フォームの表示
		$this->addViewVar('shop_search_form', $this->newForm('shop_search'));

		// 検索の実行、レコード取得
		$this->addViewVar('shop_records', $this->newModel('v_shop')->_getRecords()->addSearch($condition_sentences, $condition_values));
	}

}
?>

ページング情報の表示（ビュー）

$shop_search_form->getFormHtml()や$shop_records->getListHtml()を使って省略しています。

<form action="<?= $_self_url; ?>" method="get">
<?= $shop_search_form->getFormHtml() ?>
<input type="submit" value="送信">
</form>
<?= $shop_records->getListHtml() ?>

前後のページ

前ページ：レコード処理
次ページ：モデルに関する画面のHTML自動生成

ページトップへ