簡単なモジュールを作成_XOOPS
簡単なモジュールを作成
モジュールはディレクトリに格納することで、個々の機能として認識されます。そのときに、ディレクトリに入れるファイルにルールがあります。
モジュールは、XOOPSインストールディレクトリの「html/modules」内に格納されています。「各ディレクトリ名=モジュール名」となります。
モジュール名を「SimpleModule」として画面にメッセージを出すだけのページを作ります。
モジュールダウンロード:xoops_SimpleModule_20051106.zip(182)
簡単なモジュールにおけるファイル構成は以下のとおりです。これを、「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」が見えています)。
この右にあるフロッピーディスクっぽいのをクリックすると、XOOPSシステムにSimpleModuleがインストールされます。
インストールが成功すると、同じページの上の段に「SimpleModule」がインストールされているのが確認できます。
インストールはこれだけ。これでホームページ(トップページ)に戻ると、SimpleModuleがメニューから選択でき、ページが表示されることになります。
モジュールのアンインストール
モジュールをアンインストールする場合、「モジュール管理」の画面にて一度対象となるインストール済みのモジュールの「アクティブ」のチェックをはずします。そして、下の「送信」ボタンを押してください。
すると、右端にフロッピーのアイコンが出てきます。これをクリックして進めていくと、モジュールをアンインストールすることができます。
上段のリストからモジュールが消えたことを確認してから、modulesディレクトリ内から対象のディレクトリ自体をファイル削除します。モジュールをアンインストールするときは、必ずアクティブを無効にしてしてから薄めるようにしてください。
モジュールの更新(アップデート)
同じくモジュール管理の上段のリストより、対象モジュールの右端のディスク(?)のアイコンをクリックします。
これを進めるとアップデートが行われます。この作業は、対象モジュールのアップデートが行われます。
では、どのようなときにアップデートが必要なのでしょうか?
なお、モジュールを開発する場合はいちいちのアップデートが面倒なので、開発用に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)には極端に言うと文字列は入れないようにします。このリソースから引っ張ってくるようにします。
これは何のために分かれているのかというと、言語(英語、日本語、中国語など)部分をあえて分離することにより、ローカライズを楽にできるようにするためです。例えば、英語だと「english」ディレクトリ、日本語だと「japanese」ディレクトリにそのままの形で入れます。後で、対応するdefine定義の文字列値だけを変換してやればいいのです。ページデザイン・プログラムロジックから完全に分離できますよね。なお、english/japaneseの判別は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定義を記述します。
<?php define('_MI_SIMPLEMODULE_NAME', '簡単なモジュール'); define('_MI_SIMPLEMODULE_DESC','もっとも簡単なモジュールです。'); ?>
これは、XOOPSのシステム管理の「モジュール管理」でモジュールをインストールするときのモジュール名や情報を定義します。
defineは、第一引数にユニークな識別名、第二引数の代入する値を入れます。識別名については他とかぶらないユニークな名称である必要があります。また、他のモジュールで定義されているdefineと同じでもXOOPSが警告を出しますので、上記のように識別名にあえてモジュール名称を入れたほうがいいかもしれません。
英語の場合(englishディレクトリ内のmodinfo.php)は、識別名はまったく同じで値だけ英語にしています。
<?php define('_MI_SIMPLEMODULE_NAME', 'simple module'); define('_MI_SIMPLEMODULE_DESC','It is the easiest module. '); ?>
modinfo.phpのdefine定義は、後述する「xoops_version.php」で参照されています。注意点として、日本語を扱う場合にmodinfo.phpはEUCコードで保存するようにしてください。
main.php
実際のプログラム部であるphpファイル内で使用し、主にテンプレートであるHTMLファイルに入れる文字列リソースを定義します。
<?php define('_MD_TITLE', '簡単なモジュール'); define('_MD_MES', 'Hello World!!'); ?>
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)は、識別名はまったく同じで値だけ英語にしています。
<?php define('_MD_TITLE', 'simple module'); define('_MD_MES', 'Hello World!!'); ?>
注意点として、日本語を扱う場合にmain.phpはEUCコードで保存するようにしてください。
テンプレートファイルについて
モジュールの[templates]ディレクトリを作り、拡張子htmlのファイルをテンプレートとします。なお、ファイル名はXOOPSシステム全体(他のモジュール)でのテンプレートとかぶらないようにユニークにするほうがいいです。というのは、文字列リソースのmodinfo.phpと同じく、他のモジュールでも同じテンプレート名があると、実行時に警告を出す場合があるからです。
SimpleModuleでは「simplemodule_view.html」というテンプレートが1つあります。
<b><font size="4" color="#2020ff"><{$lang_title}></font></b> <hr> <{$lang_mes}><br> <hr>
見た目は普通のHTMLファイルですが、<html>や<body>タグがないのが分かります。XOOPSが最終的に出すページは、ヘッダ部・メニュー部・検索部などを含んだ1枚のものですので(<table>タグで配置される)、ここで指定したテンプレートは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による繰り返し
<table border=1> <{foreach item=result from=$data_list}> <tr> <td><{$result[0]}></td> <td><{$result[1]}></td> </tr> <{/foreach}> </table>
上記のようなテンプレート記述があった場合、PHPソース内では
$strA = array('Apple', 'Orange', 'Grape'); // テンプレート上のテーブルに1行ずつ情報を渡す for($i = 0; $i < 3; $i++) { $xoopsTpl->append('data_list', array(strval($i), $strA[$i])); }
と記載すると、実際のHTMLでは以下のように出力されることになります。
<table border=1> <tr> <td>0</td> <td>Apple</td> </tr> <tr> <td>1</td> <td>Orange</td> </tr> <tr> <td>2</td> <td>Grape</td> </tr> </table>
注意点として、このテンプレートであるHTMLファイルは、xoops_version.phpにて列挙されている必要があります。テンプレートには日本語などローカライズにて固有の文字列は入れないほうがいいのですが、もし日本語を入れる必要がある場合、EUCコードでファイル保存するようにしてください。
テンプレートファイルの変数代入はPHPでSmartyを使用するのとは微妙に書き方が異なるのが分かります(埋め込み部分は< ... > で囲む必要がある)。XOOPS固有のテンプレートの記述(書き方)ですので違いに注意するようにしてください。
説明が前後しましたが、次に「xoops_version.php」について説明します。
xoops_version.php
SimpleModuleのxoops_version.phpを見ながら進めていきます。
<?php // module name $modversion['name'] = _MI_SIMPLEMODULE_NAME; // module version $modversion['version'] = 1.00; // module description $modversion['description'] = _MI_SIMPLEMODULE_DESC; $modversion['author'] = "Y.Yutaka"; //none official module(0). $modversion['official'] = 0; $modversion['image'] = "images/logo.png"; $modversion['dirname'] = "SimpleModule"; // Admin $modversion['hasAdmin'] = 0; $modversion['adminmenu'] = ''; // Menu $modversion['hasMain'] = 1; // Templates $modversion['templates'][1]['file'] = 'simplemodule_view.html'; $modversion['templates'][1]['description'] = 'top page'; ?>
言語により表示文字列を切り替える場合は、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です。
<?php include '../../mainfile.php'; ?>
XOOPSの(XOOPSルートディレクトリの)「mainfile.php」を呼び出しています。これだけです。mainfile.phpでは、XOOPSのアクセスに必要な情報がdefineの形式で列挙されています。
index.php
これは、モジュール自身をディレクトリ指定した場合(ファイル指定が省略された場合)に呼ばれるモジュール自身のトップページになります。
http://www.xxx.yyy.zz/xoops/SimpleModule/
などとした場合に始めに呼ばれるページです。
ここにコードを記載してもいいのですが、汚れるのと可読性に欠けますので すぐに「view.php」などに飛ばすようにしています。
<?php // 一覧ページを表示する include('view.php'); ?>
view.php
これはindex.phpより呼ばれる(includeで呼ぶ)phpファイルです。ファイル名はview.phpでなくてもかまいません。任意の名前をつけるようにします。
<?php // ヘッダファイルの参照 require('header.php'); // テンプレートの設定 $xoopsOption['template_main'] = 'simplemodule_view.html'; // XOOPSヘッダの設定 include(XOOPS_ROOT_PATH.'/header.php'); // テンプレートにデータを設定する $xoopsTpl->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に列挙されているリンクからご参照ください。
Future's Laboratory 技術格納庫 2004-2013 Yutaka Yoshisaka.