!!!簡単なモジュールを作成
モジュールはディレクトリに格納することで、個々の機能として認識されます。
そのときに、ディレクトリに入れるファイルにルールがあります。
モジュールは、XOOPSインストールディレクトリの
「html/modules」内に格納されています。
「各ディレクトリ名=モジュール名」となります。
モジュール名を「SimpleModule」として
画面にメッセージを出すだけのページを作ります。
モジュールダウンロード:{{ref xoops_SimpleModule_20051106.zip}}
簡単なモジュールにおけるファイル構成は以下のとおりです。
これを、「html/modules」ディレクトリ内に格納することにより、モジュール
がXOOPSに認識されます。
[images] モジュールロゴなどの画像を格納
logo.png ロゴ画像
[language] 言語別のリソース(*.phpファイル)
[english] 英語リソース
main.php モジュール内で使うdefine定義
modinfo.php モジュール情報として使うdefine定義
[japanese] 日本語リソース
main.php モジュール内で使うdefine定義
modinfo.php モジュール情報として使うdefine定義
[sql] データベースに情報を格納する場合のテーブル定義(*.sqlファイル)
[templates] ページデザイン用のテンプレート(*.htmlファイル)
simplemodule_view.html テンプレートファイル
header.php ヘッダ用ファイルのinclude
index.php スタートページ
view.php index.phpから呼ばれる
xoops_version.php モジュール情報の記載されたファイル
!!モジュールのインストール
基本中の基本、モジュールのインストール方法です。
XOOPS管理者権限でログインし、「管理者メニュー」の「システム管理」より
「モジュール管理」を選択します。
モジュールがリストされているところに、何も書かれていないロゴがあります。
これが上記で書いた「SimpleModule」です(ロゴ自身は「images/logo.png」が見えています)。
{{ref_image xoops_img_20051107.png}}
この右にあるフロッピーディスクっぽいのをクリックすると、
XOOPSシステムにSimpleModuleがインストールされます。
インストールが成功すると、同じページの上の段に「SimpleModule」がインストール
されているのが確認できます。
{{ref_image xoops_img_20051107_2.png}}
インストールはこれだけ。これでホームページ(トップページ)に戻ると、
SimpleModuleがメニューから選択でき、ページが表示されることになります。
{{ref_image xoops_img_20051107_3.jpg}}
!!モジュールのアンインストール
モジュールをアンインストールする場合、「モジュール管理」の画面にて
一度対象となるインストール済みのモジュールの「アクティブ」のチェックをはずします。そして、下の「送信」ボタンを押してください。
{{ref_image xoops_img_20051107_4.png}}
すると、右端にフロッピーのアイコンが出てきます。これをクリックして進めていくと、モジュールをアンインストールすることができます。
{{ref_image xoops_img_20051107_5.png}}
上段のリストからモジュールが消えたことを確認してから、modulesディレクトリ内から対象のディレクトリ自体をファイル削除します。
モジュールをアンインストールするときは、必ずアクティブを無効にしてしてから薄めるようにしてください。
!!モジュールの更新(アップデート)
同じくモジュール管理の上段のリストより、対象モジュールの右端のディスク(?)の
アイコンをクリックします。
{{ref_image xoops_img_20051107_6.png}}
これを進めるとアップデートが行われます。この作業は、対象モジュールのアップデートが行われます。
では、どのようなときにアップデートが必要なのでしょうか?
なお、モジュールを開発する場合はいちいちのアップデートが面倒なので、
開発用にXOOPS環境を入れて「html/modules/SimpleModule」内のファイルを直接
いじりながら進めていくのがてっとり早いと思います。
下記の場合、モジュールをアップデートしないと変更が反映されません。
*テンプレートである「templates/*.html」が変更されたとき
*「xoops_version.php」内の構成が変更されたとき
*「sql/*.sql」にて、データベース構成が変更されたとき
*「language/*」内の言語リソースが変更されたとき
下記の場合はモジュールのアップデートは不要です。
*実際のプログラム部である「*.php」が変更された場合
*画像ファイル「images/*」が変更された場合
この場合はブラウザ再読込だけで変更が反映されます。
というのも、XOOPSシステムはモジュールインストール作業やデータベース構成などの
「XOOPS本体で持たなければならない情報」以外は、直接にインストール
したモジュールディレクトリ内を参照しているためです(普通のHTMLページやPHPページの更新作業と変わらないわけです)。
頻繁な更新作業やデバッグ作業では、この「アップデート」はよく使います。
効率よくモジュールを作るため、いつアップデートが必要になるのか、は覚えておいて損はないです。
では、次に実際にサンプルモジュールであるSimpleModuleディレクトリの中を見ていきましょう。
!!ディレクトリのひな形を作る
以下のような構成は、あらかじめモジュール作成のひな形として
用意しておいたほうが楽かもしれません。
フルスクラッチで一からモジュールを作る説明を順を追ってします。
[images]
[language]
[japanese]
main.php
modinfo.php
[english]
main.php
modinfo.php
[sql]
[templates]
header.php
index.php
xoops_version.php
ここから拡張していきます。[images][sql][templates]ディレクトリは
今はカラで結構です。
また、それぞれの*.phpファイルとりあえずカラファイルで。
[images]には、ロゴなどの画像ファイルを入れます。また、モジュールで使う画像ファイルがあれば、それもここに入れます。
SimpleModulesでは、ロゴ画像として「logo.png」が入ってます(関連付けはxoops_version.phpで行いますが、それは後述します)。
[language]はページに表示する文字列に対するリソース情報です。
テンプレートファイル(templates/*.html)には極端に言うと
文字列は入れないようにします。このリソースから引っ張ってくるようにします。
{{ref_image xoops_img_20051107_7.png}}
これは何のために分かれているのかというと、言語(英語、日本語、中国語など)部分
をあえて分離することにより、ローカライズを楽にできるようにするためです。
例えば、英語だと「english」ディレクトリ、日本語だと「japanese」ディレクトリに
そのままの形で入れます。後で、対応するdefine定義の文字列値だけを変換してやればいいのです。
ページデザイン・プログラムロジックから完全に分離できますよね。
なお、english/japaneseの判別はXOOPSシステム自体が行いますので「どの言語を割り当てるのか」は指定する必要はありません(「[[英語・日本語の切り替え|英語・日本語の切り替え_XOOPS]]」参照)。リソースとして分かれていればOKです。
!!文字列リソースファイルについて
モジュールの[language]ディレクトリを作り、それに言語ごとのディレクトリを作ります。日本語の場合は[japanese]、英語の場合は[english]、ほか・・・何が対応しているのかというドキュメントがないので分からないですが、piCal/TinyDなどの
モジュール内を見る限りは、
french/german/nederlands/russian/spanish/swedish/tchineseなど。
「XOOPS 2.0.13a JP」だととりあえずは、japaneseとenglishだけ用意しておく、
ということで続けていきます。
ファイル構成としては以下のようになります。
[language]
[japanese]
main.php
modinfo.php
[english]
main.php
modinfo.php
言語が違ってもファイル構成および、中身のdefineは
与える文字列を除いてはすべて同じものとなります。
個々の言語ごとに「modinfo.php」「main.php」の2ファイルが必要となります。
!modinfo.php
モジュールインストール時に参照するdefine定義を記述します。
これは、XOOPSのシステム管理の「モジュール管理」でモジュールをインストールするときのモジュール名や情報を定義します。
defineは、第一引数にユニークな識別名、第二引数の代入する値を入れます。
識別名については他とかぶらないユニークな名称である必要があります。
また、他のモジュールで定義されているdefineと同じでもXOOPSが警告を出しますので、
上記のように識別名にあえてモジュール名称を入れたほうがいいかもしれません。
英語の場合(englishディレクトリ内のmodinfo.php)は、識別名はまったく同じで値だけ英語にしています。
modinfo.phpのdefine定義は、後述する「xoops_version.php」で参照されています。
注意点として、日本語を扱う場合にmodinfo.phpはEUCコードで保存するようにしてください。
!main.php
実際のプログラム部であるphpファイル内で使用し、主にテンプレートであるHTMLファイルに入れる文字列リソースを定義します。
PHPソース内(view.php)では以下のように参照されます。
$xoopsTpl->assign('lang_title', _MD_TITLE);
$xoopsTpl->assign('lang_mes', _MD_MES);
上記だと、テンプレートファイルでのlang_titleに「_MD_TITLE」で指定されている「簡単なモジュール」が入ります。
lang_mesに「_MD_MES」で指定されている「Hello World!!」が入ります。
英語の場合(englishディレクトリ内のmain.php)は、識別名はまったく同じで値だけ英語にしています。
注意点として、日本語を扱う場合にmain.phpはEUCコードで保存するようにしてください。
!!テンプレートファイルについて
モジュールの[templates]ディレクトリを作り、拡張子htmlのファイルをテンプレートとします。なお、ファイル名はXOOPSシステム全体(他のモジュール)でのテンプレートと
かぶらないようにユニークにするほうがいいです。
というのは、文字列リソースのmodinfo.phpと同じく、他のモジュールでも同じテンプレート名があると、実行時に警告を出す場合があるからです。
SimpleModuleでは「simplemodule_view.html」というテンプレートが1つあります。
<{$lang_title}>
<{$lang_mes}>
見た目は普通のHTMLファイルですが、やタグがないのが分かります。
XOOPSが最終的に出すページは、ヘッダ部・メニュー部・検索部などを含んだ1枚のものですので(タグで配置される)、ここで指定したテンプレートは
XOOPSが最終的に出すHTMLファイルに対して一部品として埋め込まれます。
文字コード指定のMETAタグなどは意識しなくても問題ありません。
<{$xxxxx}>
という部分にて、変数名xxxxxに指定した値を埋め込む、となります。
実際はプログラム部であるPHPソース内で
$xoopsTpl->assign('xxxxx', '何か文字列');
のように割り当てます。
日本語をそのままHTML内の文字列としてテンプレートに書き込むのはナンセンスですので、文字列のリソース(languageディレクトリ内のmain.php)で代入できるようにします。
そのほか、ifやforeachなどの条件分岐、繰り返し処理も使うことが可能です。
!テンプレートでのifによる条件分岐
<{if $item1 == 1}>
item1が1の場合に出力されるHTML内容
<{else}>
item1が1以外の場合に出力されるHTML内容
<{/if}>
上記のようなテンプレート記述があった場合、PHPソース内では
$xoopsTpl->assign('item1', '1');
のようにすると、テンプレート上の「$item1 == 1」のときの処理が行われます。
!テンプレートでのforeachによる繰り返し
<{foreach item=result from=$data_list}>
<{$result[0]}> |
<{$result[1]}> |
<{/foreach}>
上記のようなテンプレート記述があった場合、PHPソース内では
$strA = array('Apple', 'Orange', 'Grape');
// テンプレート上のテーブルに1行ずつ情報を渡す
for($i = 0; $i < 3; $i++) {
$xoopsTpl->append('data_list', array(strval($i), $strA[$i]));
}
と記載すると、実際のHTMLでは以下のように出力されることになります。
注意点として、このテンプレートであるHTMLファイルは、xoops_version.phpにて
列挙されている必要があります。
テンプレートには日本語などローカライズにて固有の文字列は入れないほうがいいのですが、もし日本語を入れる必要がある場合、EUCコードでファイル保存するようにしてください。
テンプレートファイルの変数代入は[[PHPでSmartyを使用する|テンプレートエンジン(Smarty)_PHP]]のとは
微妙に書き方が異なるのが分かります(埋め込み部分は< ... > で囲む必要がある)。
XOOPS固有のテンプレートの記述(書き方)ですので違いに注意するようにしてください。
説明が前後しましたが、次に「xoops_version.php」について説明します。
!!xoops_version.php
SimpleModuleのxoops_version.phpを見ながら進めていきます。
言語により表示文字列を切り替える場合は、languageの「modinfo.php」
にてdefine定義するようにします。
!$modversion['name']
モジュールの名称を指定します。
実際にメニューに表示される文字列です。
システム管理の「モジュール管理」画面で任意の文字列に変更することも可能です。
!$modversion['version']
モジュールのバージョンを指定します。
システム管理の「モジュール管理」画面での「バージョン情報」にて表示されます。
!$modversion['description']
モジュールの説明文を指定します。
システム管理の「モジュール管理」画面での「バージョン情報」にて表示されます。
!$modversion['author']
モジュールの作成者名を指定します。
システム管理の「モジュール管理」画面での「バージョン情報」にて表示されます。
!$modversion['official']
XOOPS標準のモジュールの場合は1です。
普通は、常に0を指定します。
!$modversion['image']
ロゴ画像のファイル名を指定します。
システム管理の「モジュール管理」画面に表示されます。
ロゴ画像は標準モジュールと同じサイズで、92 x 52 pixelの画像にあわせるのがいいかと思います。
!$modversion['dirname']
モジュールのディレクトリ名と同じ文字列を指定します。
!$modversion['hasAdmin'] / $modversion['adminmenu']
システム管理者でXOOPSにログインした場合の、管理メニューに出す場合は
「$modversion['hasAdmin']」を1にします。
!$modversion['hasMain']
トップページの「メインメニュー」に項目として表示する場合は1とします。
0を指定した場合、メニューに対象モジュールを選択する項目が表示されません。
ライブラリ的な(表に出さない)モジュールをもし作る場合は0にするといいかも
しれません。
0指定の場合は、システム管理の「モジュール管理」画面では、「表示順」が常に0になり、変更ができない(=メインメニューには表示されない)状態となります。
!$modversion['templates']
テンプレートファイルの関連づけを行います。
モジュールで使用する(参照できる)テンプレートはすべてここに「配列として」
列挙しておく必要があります。
$modversion['templates'][1]['file'] = 'simplemodule_view.html';
$modversion['templates'][1]['description'] = 'top page';
3次元配列となっており、2番目の添え字は1から始まることに注意してください(0からではないです)。
「$modversion['templates'][1]['file']」にて、[templates]ディレクトリ内の
テンプレート名を指定します。
「$modversion['templates'][1]['description']」にて、指定した1番目のテンプレートの説明文を指定します。日本語を扱う場合(多言語で切り分けたい場合)は、
[language]の文字列リソース(modinfo.php)に定義されたdefine名称を指定するように
します。
もし、複数のテンプレートを記載する場合は、以下のように順番に列挙するようにします。その際2つめの添え字は1、2、3...のように+1していきます。
$modversion['templates'][1]['file'] = 'simplemodule_view.html';
$modversion['templates'][1]['description'] = 'top page';
$modversion['templates'][2]['file'] = 'simplemodule_append.html';
$modversion['templates'][2]['description'] = 'append page';
$modversion['templates'][3]['file'] = 'simplemodule_update.html';
$modversion['templates'][3]['description'] = 'update page';
もし、プログラム部であるPHPソース内でテンプレートを参照しているにもかかわらず、
このxoops_version.phpの「$modversion['templates']」で指定がなかった場合、
XOOPS自身が挙動不審になります。
「うまいことテンプレートが参照されていない」「ページが表示されていない」
といった場合は、このxoops_version.phpの指定が間違ってないか確認するようにしましょう。
まれにですが、キャッシュか何かの問題でxoops_version.phpもPHPソースも正しいのに
動作が不安定・ページが表示されない、などの問題が起こることがあります。
この場合は、ブラウザのキャッシュをクリアする・一度XOOPSをログアウトして
再度モジュールをインストールし直してみる、などしてみてください。
!!プログラム部(PHPソース)を記述する
リソース類・モジュール情報類(文字列リソース、テンプレート、xoops_version.php)の説明は一通り説明しましたので、最後、
コアとなるプログラム部分の説明を行います。
最低限必要なのは「header.php」「index.php」の2つです。
実際は、index.phpからheader.phpを呼び出しているのでindex.phpにすべて
書いてもいいのですが、定型文ですのでheader.phpは別途で分けています。
なお、注意点としてこれらのphpファイルもやはり、すべてEUCコードで保存するようにしてください(コメントのみ日本語を使っている場合でも)。XOOPS自体はEUCで動いてますので、仮にソース部分の一部がShift-JISなどだったりすると、怪しい動作をする場合があります。
!header.php
固定で以下の3行のみでOKです。
XOOPSの(XOOPSルートディレクトリの)「mainfile.php」を呼び出しています。
これだけです。
mainfile.phpでは、XOOPSのアクセスに必要な情報がdefineの形式で列挙されています。
!index.php
これは、モジュール自身をディレクトリ指定した場合(ファイル指定が省略された場合)に呼ばれるモジュール自身のトップページになります。
http://www.xxx.yyy.zz/xoops/SimpleModule/
などとした場合に始めに呼ばれるページです。
ここにコードを記載してもいいのですが、汚れるのと可読性に欠けますので
すぐに「view.php」などに飛ばすようにしています。
!view.php
これはindex.phpより呼ばれる(includeで呼ぶ)phpファイルです。
ファイル名はview.phpでなくてもかまいません。任意の名前をつけるようにします。
assign('lang_title', _MD_TITLE);
$xoopsTpl->assign('lang_mes', _MD_MES);
// XOOPSフッタの設定
include(XOOPS_ROOT_PATH.'/footer.php');
?>
それぞれを実行する順番が大事になります。
まず一番始めに「header.php」を呼び出しています。これは先頭に書くようにしてください。
header.phpでは、「../../mainfile.php」を呼んでいます。これで、XOOPSのモジュール実行に必要なdefine定義を行います。
ログインしているかどうか、ログインユーザ情報・グループ情報を取得する場合は、
これを呼び出した後に行うことができます。
$xoopsOption['template_main'] = 'simplemodule_view.html';
にて、ページを表示する際のテンプレート名を指定します。
xoops_version.phpの「$modversion['templates']」で列挙したテンプレート名で
ある必要があります。
include(XOOPS_ROOT_PATH.'/header.php');
にて、XOOPSのルートディレクトリのheader.phpを呼んでいます。
ログインしているユーザ権限ごとの判定、テーマ設定、などXOOPS本体がしなければならない処理を行います。
$xoopsTpl->assign('lang_title', _MD_TITLE);
$xoopsTpl->assign('lang_mes', _MD_MES);
にて、テンプレート(ここでは「simplemodule_view.html」)の
変数に指定する文字列を割り当てます。
「_MD_TITLE」「_MD_MES」は、[language]ディレクトリのmain.phpのdefine定義から参照されます(日本語、英語などの言語の振り分けは意識する必要はありません)。
include(XOOPS_ROOT_PATH.'/footer.php');
一番最後に、XOOPSルートディレクトリのfooter.phpを呼んでいます。
ここで、HTMLを閉じます。これを呼ぶと、最終的なHTMLファイルが出力されます。
!!終わりに
上記で、非常に簡単ですがSimpleModuleとして一番簡単なXOOPSモジュール生成の
説明は終わりです。
しかし、「ほら、簡単にできるでしょ」とは言えないですね(^_^;;。
ただ、上記のようなひな形をあらかじめ用意しておいて拡張していく(コピー&ペースト作戦)、で効率アップは図ることができるかもしれません。
その他のDBアクセスやログインユーザ情報取得などのTipsは、[[PHP & XOOPS|PHP & XOOPS]]に列挙されているリンクからご参照ください。