[pod] [xml]

名前

CGI::Explorer - CGIスクリプトの運用において、木構造のデータを管理するクラス

バージョン

このドキュメントは2001年3月23日にリリースされたCGI::Explorerバージョン1.12 のドキュメントに関連します。

概要

これはテスト用のコードですが、(#!)で始まる行が1行目でなくてはなりません。

	#!/usr/Bin/Perl
	use strict;
	use warnings;
	use CGI;
	use CGI::Explorer;
	my($q)		= CGI -> new();
	my($tree)	= CGI::Explorer -> new();
	my($dir)	= 'D:/My Documents/HomePage';
	$tree -> from_dir($dir);
	my($state)	= $tree -> state($q); # from_dir()又はfrom_hash()に続かなければならない。
	my($tree_set)	= $tree -> as_HTML($q);
	my($result_set)	= 'Id: ' . $tree -> current_id() . '. Name: ' . $tree -> name();
	print	$q -> header(),
			$q -> start_html(),
			$tree -> css(),
			$q -> start_form({action => $q -> url()}),
			$q -> hidden({name => 'explorer_state', value => $state, force => 1}),
			$q -> table
			(
				{border => 1},
				$q -> Tr
				([
					$q -> td($tree_set) .
					$q -> td($result_set),
				])
			),
			$q -> end_form(),
			$q -> end_html();

これをカットアンドペーストした後、多くて2行の変更だけが必要です:

説明

CGI::ExplorerはCGIスクリプトをサポートしたモジュールです。ツリーを 表示し、ユーザーがノードのアイコンをクリックすることでノードの オープンやクローズができるようデータのツリーを管理します。

オープンされたノードは全ての子ノードを表示し、そしてオープンされた/クローズ されたと言う情報を復元します。

クローズされたノードは全ての子ノードを隠します。

new(click_text => 1)を用いたときでも、ノードのテキストのクリック時に ノードのオープン/クローズされた状態を切り替えることはありません。

大要

CGI::Explorerは毎回スクリプトが呼び出される度に木の内部表現を 再構築します。

いくつかのデータはスクリプトが呼び出すfrom_dir()またはfrom_hash()に 由来し、またいくつかのデータは以前のスクリプトの呼び出しによるCGI フォームフィールドに由来します。

特に、各ノードのオープン/クローズされた状態はブラウザへのスクリプトの呼び出し から'フォームのsubmit'を経て、次のスクリプトの呼び出しへと送信され往復して 戻って来ます。

submitをクリックすることによっても、そのようにクリックされたノードのidが 渡され、２度目のスクリプトの呼び出しで戻って来ます。new()のオプションが click_text => 1の時、ノードのテキストをクリックすることでもsubmitすることと 同じになります。

状態の維持に関しては複雑な問題があり、もっと下のほうで議論されています。 'state'メソッドを御覧下さい。

コンストラクタと初期化

new(...)はCGI::Explorerオブジェクトを返します。

これはクラスのコンストラクタです。

new()を呼び出すことは以下と等価です:

new(click_text => 0, css => '...', image_dir => '/images', show_current => 1, show_id => 1, show_name => 1, sort_by => 'name')

オプション:

ノードのアイコン

CGI::Explorerにはアイコンのセットが同梱れており、それぞれのアイコンは PNG及びGIFです。

デフォルトはGIFで、より多くのブラウザが透過PNGよりも透過GIFをサポートしている からです。

GIFの圧縮アルゴリズムの使用に関するUniSysのライセンスを気にする必要は ありません。なぜならばそれらのGIFは圧縮されていないからです :-)。

make fileはこれらのファイルを自動的にインストールしてくれません。あなたは それらをドキュメントルート下に手動でインストールしなくてはならず、それから image_dirオプションを用いることでこれらのファイルがある場所に指定しなくては なりません。

多くのGIFはMySQLToolと呼ばれるパッケージに由来するものです。不幸なことに このプログラムの作者はダウンロードURIにパッケージを置き忘れています。あなたは http://lists.dajoba.com/m/listinfo/mysqltool を見ることによって少しほっとするかもしれません。

MySQLToolで使用されているファイル名からは変更されています。

ルートノードのアイコン、そしてカレントノードのアイコンですが十分満足なものでは ありません。もしもっと良いものが使えるのであれば私にお知らせ下さい。

もし透過PNGが適切にブラウザに表示されなかった場合、ブラウザをアップデートする か、あるいはGIFを試してみて下さい。

ほとんど全てのアイコンのサイズは17 x 17固定です。例外はルートアイコンで、 サイズが固定されていないため、あなたの望むどんな画像でも扱うことができます。

アイコン画像のファイル名を変更するためにはimage($icon_id, $image_name) メソッドを使用します。

as_HTML($q)

文字列を返します。

データの内部表現をHTMLに変換して、それを返します。

_build_result(...)

内部的に使用されます。

css([$new_css])

submitボタンのためのスタイルシートを含むHTML文字列を返します。

set(css => $new_css)のように、スタイルシートをセットする目的にも 使用されます。

例としてはce.plを御覧下さい。

current_id()

'現在の'ノードidを返します。

depth($id)

idが与えられたノードの深さか、あるいは0を返します。

_depth()

内部的に使用されます。

Tree::Nary::traverse経由でdepth()が呼び出されます。

_found()

内部的に使用されます。

File::Findによって呼び出されますが、その１番目のパラメータとして$selfを 受け取らないことを意味し、またそうであることによってクラスのデータにアクセス するためにグローバルな$myselfを使わなくてはならないことを示します。

from_dir($dir_name)

何も返しません。

オブジェクトに対して、与えられたディレクトリの中の全てのサブディレクトリ名を パースすることによりデータの内部表現を構築させます。

使用方法:

出力可能なデータを解決した後、as_HTML($q)を呼び出すことになります。

例としてce.plを御覧下さい。

from_hash($hash_ref)

何も返しません。

ハッシュで与えられた情報からデータを抜粋することによりオブジェクトに対して 内部表現を構築させます。

出力可能なデータを解決した後as_HTML($q)を呼び出すことになるでしょう。

%$hash_refの各キーはユニークな正の整数で、これらのサブキーとともにハッシュの リファレンスを指しています。

例はce.plを御覧下さい。

get($option)

与えられたオプションの現在の値を返すか、又は未知のオプションである場合は undefを返します。

$tree -> get('css_background')はデフォルトで'white'を返します。

image($icon_id, $new_image)

与えられたアイコンidに関する画像ファイル名を返します。

与えられたアイコンidに対する新しい画像ファイル名を設定します。

例はce.plを御覧下さい。

プリフィクスは:

Note: これらはpod2htmlのバグのためにインデントされています: 文字列が 1列目にある時'-L'に関してそれが起こります。

name()

'現在の'ノードを返します。

parent_id()

'現在の'ノードの親のidを返します。

set()

何も返しません。

new()の呼び出しの後に、どんなオプションでも構わないのですが、値を新たに 設定するために用いられます。

set()はnew()と同じパラメーターを取ります。

state($q)

全てのノードにおけるオープン/クローズの状態を返します。

与えられたCGIオブジェクトからフォームフィールドのデータを復元することにより 内部データ表現をオブジェクトに更新させます。

Warning: このメソッドはfrom_dir()又はfrom_hash()を呼び出した後でしか 呼び出すことができません。

Warning: ブラウザへの出力とその背後を往復するようなあなたのスクリプトの おそらくは隠しフィールドとして、返り値を扱わねばなりません(must)。 この方法では次のスクリプト呼び出しで値を復元することが可能です。

これは各ノードのオープン/クローズされたと言う状態を保つための CGI::Explorerのメカニズムです。状態の維持は極めて複雑な問題が あります。詳細は以下を参照下さい:

	Writing Apache Modules with Perl and C
	Lincoln Stein and Doug MacEachern
	O'Reilly
	1-56592-567-X
	Chapter 5 'Maintaining State'

あなたは次のような問題に遭遇する可能性があります: クローズしてノードを再オープンした際、あなたはノードをクローズする前の オープン/クローズされた状態を復元することを期待します。

WindowsのExplorerでは、プログラムがRAMに留まり、駆動し、終始ノードがクリック されるため、これは単純です。したがって自身の(プロセス)メモリで各ノードの 状態を維持することが可能です。

CGIスクリプトでは、2つに分断されたスクリプトの呼び出しで状態を自身のメモリの 外部で維持しなければなりません。私はCGI::Exploererにおいては(hidden) フォームフィールドを使うことを選択しました。

例はce.plを御覧下さい。

フォームフィールドはこれらの名前です:

必要とされるモジュール

更新履歴

Changes.txtを御覧下さい。

作者

CGI::ExplorerはRon Savage<ron@savage.net.au>によって2001年 書かれました。

Home page: http://savage.net.au/index.html

著作権

Austrlian copyright (c) 2001, Ron Savage. All rights reserved.

	All Programs of mine are 'OSI Certified Open Source Software';
	you can redistribute them and/or modify them under the terms of
	The Artistic License, a copy of which is available at:
	http://www.opensource.org/licenses/index.html

翻訳者

三浦真磁<snj@users.sourceforge.jp>