- 名前
- バージョン
- 概要
- 説明
- 大要
- コンストラクタと初期化
- ノードのアイコン
- as_HTML($q)
- _build_result(...)
- css([$new_css])
- current_id()
- depth($id)
- _depth()
- _found()
- from_dir($dir_name)
- from_hash($hash_ref)
- get($option)
- image($icon_id, $new_image)
- name()
- parent_id()
- set()
- state($q)
- 必要とされるモジュール
- 更新履歴
- 作者
- 著作権
- 翻訳者
名前¶
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行の変更だけが必要です:
#!/usr/Bin/Perl
my($dir) = 'D:/My Documents/HomePage';
説明¶
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')
オプション:
click_text - デフォルトは1です
ノードのsubmitボタンに表示されるテキスト(id及びname)を生成します。
css - デフォルトは<a very long string>です。詳細を知りたい場合は ソースコードを御覧下さい。
click_text == 1の時、submitボタンのためのスタイルシートを適用して使用 するためのものです。
デフォルトではスタイルシートが適用されます。そうです、私はスタイルシートを 適用したテキストのsubmitボタンの幅が実に広くなりすぎてしまうことを 知っています。けれども、あなたにソースを見てもらったとしても、 私は幅を狭くするスタイルシートのコマンドを見付けることはできません。
css_backgorund - デフォルトは'white'です
submitボタンの背景色です。
css_color - デフォルトは'navy'です
submitボタンの前景色です。
image_dir - デフォルトは'/images'です
アイコンのあるwebサーバーの特殊なディレクトリです。
Note: ディレクトリはオペレーティングシステムにおけるパスではなく、 webサーバーのドキュメントルートに関するものです。
show_current - デフォルトは1です
'現在の'ノードに対して特殊なアイコンを表示します
show_id - デフォルトは1です
ノードのアイコンの右側に、ノードのidを表示します。
show_name - デフォルトは1です。
ノードのアイコンの右側かつ(もしshow_id == 1の場合)ノードのidの 右側にノードの名前を表示します。
もしshow_id == 0 && show_name == 0の場合は何も表示されません。
sort_by - デフォルトは'name'です
(どのような場合でも)'name'にセットした場合、名前でノードをソートします。 'id'にセットした場合はidでソートを行います。ソートは同じ階層の全ての ノードに対して行われます。
ノードのアイコン¶
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)¶
何も返しません。
オブジェクトに対して、与えられたディレクトリの中の全てのサブディレクトリ名を パースすることによりデータの内部表現を構築させます。
使用方法:
$tree -> from_dir('/home/rons');
$tree -> from_dir('D:\My Documents');
$tree -> from_dir('D:/My Documents');
出力可能なデータを解決した後、as_HTML($q)を呼び出すことになります。
例としてce.plを御覧下さい。
from_hash($hash_ref)¶
何も返しません。
ハッシュで与えられた情報からデータを抜粋することによりオブジェクトに対して 内部表現を構築させます。
出力可能なデータを解決した後as_HTML($q)を呼び出すことになるでしょう。
%$hash_refの各キーはユニークな正の整数で、これらのサブキーとともにハッシュの リファレンスを指しています。
id - ユニークな正の整数で、各ノードで異なります
これはノードの識別子です。コンストラクタのオプションではnew(show_id => 1) とすることによって表示されますが、これはデフォルトです。
そうです、これはTree::Naryに依存したコードの内部で用いるための $hash_key内に含まれるキーのコピーなのです。
name - 文字列です
これはノードの名前です。コンストラクタオプションnew(show_name => 1)を 用いることによって表示させることができますが、これはデフォルトです。
parent_id - 整数です
これはこのノードの親の識別子です。
idとparent_id間での関係がツリーのデータを形成します。
0はノードが親を持っていないことを示します。すなわちこのノードは仮想的なルート ノードの子と言えます。事実上、各
CGI::Explorerのオブジェクトが 自身のルートノードを形成しています。よってあなたはルートノードを意識して 作る必要が無いのです。もしあなたがidが1(と言う)ルートノードを持つとすると、あなたのルートノードの 親は0のままで、次のレベルのノードは全て1と言う親のidになるでしょう。
例はce.plを御覧下さい。
get($option)¶
与えられたオプションの現在の値を返すか、又は未知のオプションである場合は undefを返します。
$tree -> get('css_background')はデフォルトで'white'を返します。
image($icon_id, $new_image)¶
与えられたアイコンidに関する画像ファイル名を返します。
与えられたアイコンidに対する新しい画像ファイル名を設定します。
例はce.plを御覧下さい。
プリフィクスは:
-
'root' - ルートアイコンです -
'**' - カレントのアイコンです -
'-L' - それより下に兄弟を持たないオープンなノードです -
'--' - それより下に兄弟を持つオープンなノードです -
'+L' - それより下のほうに兄弟を持たないクローズされたノードです -
'+-' - それより下ほうに兄弟を持つクローズされたノードです -
' L' - それより下のほうに兄弟を持たず子を持たないノードです -
' -' - それより下のほうに兄弟を持ち、子を持たないノードです -
' ' - 水平スペースです -
'| ' - 垂直コネクタです
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を御覧下さい。
フォームフィールドはこれらの名前です:
explorer_id_(\d+) - クリックされたノードのid
ノードごとにこのようなフィールド１つずつがあります。
このノード、あるいはこのノードのテキストをクリックする (click_text => 1の時)。(\d+)はユニークな正の整数です。
あなたのCGIスクリプトではこれらのフォームフィールド出力する必要がありません。 as_HTML($q)がこれをあなたのためにやってのけます。
explorer_state - 全ノードのオープン/クローズされた状態です。値は文字列です。
あなたのCGIスクリプトでこの値を出力しなければなりません。
例としてはce.plを御覧下さい。
必要とされるモジュール¶
Tree::Naryが必要です。Perlにはあらかじめ入っていません。 CPANあるいはあなたの近辺で入手して下さい。
更新履歴¶
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>