Module Making Tutorial

xoops モジュール作成チュートリアル (xoops 2.x 向け)

2004/02/24 日本ノーベル株式会社

本ドキュメントの目的 このドキュメントは、xoops 2.x のモジュールを作成するにあたっての参考資料です。 環境 このドキュメントを作成するにあたって、動作を確認した環境は下記の通りです。 OS Linux 2.6.3 glibc

2.3.3_pre20040207

xoops

2.0.6

apache

2.0.48

MySQL

4.0.17

mod_php

4.3.4

本ドキュメントの対象者 本ドキュメントは下記の前提条件を満たす方向けに作成されています。 • • • • •

php の基本的な構文を習得していること。 xoops の管理者としての操作方法を習得していること。 特に、標準モジュール以外の追加モジュールのインストールの経験があること。 MySQL の基本的な SQL 文の記述方法、データベースの設計方法を習得していること。 UNIX（とくにディレクトリ構造や、その操作）の知識を習得していること。 php のテンプレートシステム(smarty)の基本的な構文を習得していること。

文責 本ドキュメントは日本ノーベル株式会社が独自に作成したドキュメントであり、全ての文責は当社 にあります。 その他 xoops 開発チームおよび、いかなるコミュニティ・個人も本ドキュメントの作成には関与して おりません。本ドキュメントに関するお問い合わせは御遠慮下さい。 免責事項 本ドキュメントの内容につきましては、誤りの無いよう確認作業の上作成していますが、その完全 性を保証することはできません。 また、xoops 本体のバージョンアップに伴い、本ドキュメントの内容との不一致が生じる恐れがあり ます。 本ドキュメントをご活用の際は上記の可能性を十分把握して頂きますようお願いします。 当社は本ドキュメントの参照によって生じたいかなる責を負うものではないことをご了解ください。 ご注意 本ドキュメントではその内容の簡潔さを求めるために、言語ファイルの使用・解説を省略していま す。この点にきましては、今後の改訂版にて記載する予定です。

スケルトンモジュールのインストール 本ドキュメントでは、新規モジュールの開発の初期作業を容易にするために用意された「スケルト ンモジュール」をベースにチュートリアルを進めます。 まずは、スケルトンモジュールをインストールすることからはじめましょう。 スケルトンモジュールは modules ディレクトリに展開してください。 すると、管理者メニュー → モジュール管理の下半分に、スケルトンモジュールが表示されますの で、インストールしてください。

（重要）スケルトンモジュールから、別モジュールを作成するときの注意点 スケルトンモジュールから別モジュールを作成するときには、インストールの前に、モジュールディ レクトリの名前を変更しますが、合わせて、xoops_version.php 内の$modversion['dirname']を変更 する必要があります。 xoops_version.php:

$modversion = array( 'name' => 'スケルトン', 'version' => '1.00', 'description' => 'スケルトンモジュール
モジュールを作成するときの骨組みとして 使える、サンプルモジュールです', 'credits' => 'Japan Novel Inc.', 'author' => 'Hiroyuki Toda ([email protected])', 'help' => '', 'license' => 'GPL2 see LICENSE', 'official' => 0, 'image' => 'images/skelton_slogo.png', 'dirname' => 'skelton', );

この$modversion['dirname']を変更し忘れると、各種設定ファイルとしてスケルトンモジュールのファ イルが使用されてしまいます。 インストール前に必ず修正しましょう。 その他の値の意味はそれぞれ下記の通りです。 必要に応じて変更してください。 name

モジュール名

version

バージョン

description

モジュールの説明

credits

著作権者

auther

著作者

help

ヘルプ html ファイル（空でも可）

license

ライセンス

official

標準モジュールの場合は 1, それ以外は 0

image

ロゴファイルのパス

dirname（重要）

モジュールのディレクトリの名前

設定を反映させるには、モジュールのアップデートが必要です。 また、スケルトンモジュールでは DB 上に skelton_table1 skelton_table2 skelton_table3 という 3 つのテーブルを作成します。このテーブル名も衝突しないよう変更が必要です。 変更は sql/mysql.sql と、xoops_version.php 内の$modversion['tables']の 2 ヵ所です。 create table skelton_table1 ( name text not null ); create table skelton_table2 ( name text not null ); create table skelton_table3 ( name text not null );

$modversion['tables'] = array ( 'skelton_table1', 'skelton_table2', 'skelton_table3', );

こちらもインストール前に忘れずに変更するようにしてください。

モジュールの構造 ディレクトリ内のファイル・ディレクトリのうち、その名前と役割が確定しているのは下記の通りです。 index.php

ファイル

モジュールのトップページ

xoops_version.php

ファイル

モジュールの設定ファイル

templates/

ディレクトリ

ページ用のテンプレートファイルを置くディレクトリ

templates/blocks/

ディレクトリ

ブロック用のテンプレートファイルを置くディレクトリ

blocks/

ディレクトリ

ブロック用のコードファイルを置くディレクトリ

名前と役割が慣例上決まっているファイル・ディレクトリは下記の通りです。 admin/

ディレクトリ

管理者用設定ファイル、コードファイルを置くディレクトリ

admin/index.php

ファイル

管理者操作用コードを置くファイル

admin/menu.php

ファイル

管理者メニューの中身を定義したファイル

header.php

ファイル

../../mainfile.php ファイルを include するファイル 同時に、モジュールで共用される変数や関数、クラスなどの定 義（別ファイルの include）を行う

sql/

ディレクトリ

モジュールインストール時のデータベースの初期化を行うファ イルを置くディレクトリ

sql/mysql.sql

ファイル

MySQL 用の初期化ファイル（sql 文）

images/

ファイル

ロゴなどの画像データを置くディレクトリ

モジュールのアップデートが必要なとき xoops はモジュールに関連する情報の一部をキャッシュしています。 下記のような更新を行った場合は、モジュールのアップデートを実施して、キャッシュ情報を更新 してください。 • • •

xoops_version.php の情報を更新した場合 admin/menu.php の情報を更新した場合 templates/, templates/blocks/ディレクトリ内のテンプレートファイルを更新した場合

モジュールの再インストールが必要なとき 場合によっては、モジュールのアップデートではなく、モジュールの再インストールが必用なことが あります。 • •

sql/ディレクトリ内の*.sql ファイルを更新した場合 新しいブロックを追加した場合

モジュールの再インストールは、アップデートを兼ねますので、迷ったらモジュールの再インストー ルを行うのがお勧めです。

ページを追加する (テンプレートを使用しない場合) モジュールのアップデート: 不用 skelton_page_without_template.php をコピーして、編集するだけです。 ブラウザから、直接ファイルの URL を指定してください。 modules/<モジュールディレクトリ名>/<ファイル名>

include 'header.php'; include XOOPS_ROOT_PATH.'/header.php'; // ここにページ本文を書こう！ echo "Hello, World!\n"; include XOOPS_ROOT_PATH.'/footer.php';

XOOPS_ROOT_PATH/header.php, XOOPS_ROOT_PATH/footer.php の読み込みにより、それぞ れヘッダ部分およびフッタ部分が生成されます。 これを忘れると、メニューも表示されなくなりますので、必ず include するようにしてください。 また、このケースではテンプレートシステムは使用しませんので、直接 html コードを echo などで記 述する必要があります。

ページの追加(テンプレートを使用する場合) モジュールのアップデート: 新しいテンプレートを追加する場合は必要 まず、テンプレートを追加します。テンプレートファイルは templates ディレクトリに作成してください。 （templates/blocks ではありませんので注意） テンプレートを追加したら、xoops_versions.php ファイルの$modversion['templates']にエントリを追 加します。 $modversion['templates'] = array ( array ( 'file' => '[ファイル名]', 'description' => ''), array ( 'file' => '[ファイル名]', 'description' => ''), array ( 'file' => '[ファイル名]', 'description' => ''), );

←この行を追加

file にはテンプレートファイル名（ディレクトリ名は入れない） description にはテンプレートの説明（空でも可）を記述してください。 エントリが追加できたら、モジュールのアップデートをしましょう。

ページファイルについては、skelton_page_with_template.php をコピーして編集しますが、必ずど のテンプレートを使用するのかを選択するために$xoopsOption['template_main']変数にテンプレー トファイル名を格納しなければいけないことに注意してください。

include 'header.php'; $xoopsOption['template_main'] = 'skelton_template.html';

//テンプレートファイルの選択

include XOOPS_ROOT_PATH.'/header.php'; // ここにページの処理を書こう！ // 注意！: テンプレート使うページは echo 文を使ってはいけません。 // $xoopsTpl 変数にリソースをセットすること。 $xoopsTpl->assign('message', "Hello, World!\n"); //リソースの assign include XOOPS_ROOT_PATH.'/footer.php';

コメントにもあるとおり、テンプレートを使用するページでは、echo などは使用してはいけません。 $xoopsTpl の assign, append メソッドなどを使用して、テンプレート変数に値をセットしていきます。

テンプレートファイルについての注意点 smarty の標準の開始区切り、終了区切りはそれぞれ「{」、「}」ですが、xoops 環境ではそれぞれが 「<{」、「}>」と変更されていますので注意が必要です。 正: This is a skelton template. <{$message}>

誤: This is a skelton template. {$message}

これに伴い、コメントの区切りもそれぞれ「<{*」、「*}>」となります。

DB へのアクセス方法 ページ内、ブロック内でデータベースにアクセスする場合、mysql_connect, mysql_query, mysql_fetch_array 等を直接コールしてはいけません。 xoops は現在は MySQL のみの対応となっていますが、その他のデータベースにも対応する方向 で開発が進められており、データベースの差異を吸収するための Database クラスが用意されてい ます。 データベースにアクセスするための方法はいくつかありますが、基本的にはグローバルオブジェク トである$xoopsDB を使うのが通例です。 尚、$xoopsDB を関数内で使用する場合は global $xoopsDB;宣言を行う必要が有ることに注意し てください。 function xxxxxxx() { global $xoopsDB; …… }

尚、$xoopsDB はスクリプトの開始時点で自動的にデータベースへの接続を行い、スクリプトの終 了時点で自動的にデータベースへの切断を行います。手動による open, close 処理は不用です。 (というより、してはいけません) $xoopsDB グローバルオブジェクトによるデータベースの操作 $xoopDB グローバルオブジェクトを用いた典型的なデータベースの操作の手順は下記の通りで す。 $result = $xoopsDB->query(“select uname from “. $xoopsDB->prefix(“users”)); echo “ユーザ数: “. $xoopsDB->getRowsNum($result); foreach(list($uname) = $xoopDB->fetchRow($result)){ echo “>> $uname
\n”; }

query メソッドは SQL 文の発行、 getRowsNum メソッドは SQL 文(select 文)による選択行数の取得、 fetchRow メソッドは選択された行の取得を行います。 注意事項としては、全てのテーブル名には自動的に prefix(通常”xoops”)が付与されていますの で、prefix メソッドで prefix 付きのテーブル名を取得して、そのテーブル名を query メソッドに引き わたす必要があることに注意してください。 $xoopsDB->prefix(“users”) の値: Prefix

$xoopsDB->prefix(“users”)

xoops(デフォルト)

xoops_users

jn_xoops

jn_xoops_users

some_system

some_system_users

スクリプトから見たとき、prefix がどうなっているかは実行してみるまで確認できません。 勝手に”xoops”だろうと決め打ちをしてしまうと、SQL 文が失敗してしまいます。 面倒ですが、必ず prefix メソッドを利用してください。 また、query メソッドは GET アクセス時には select 文しか発行できないという制限がかけられていま す。(先頭 6 文字が”select”でないとエラーになる) POST アクセス時にはこのような制限は有りません。 GET アクセス時に select 文以外の SQL 文を発行する場合は、化わりに queryF メソッドを使用して ください。queyrF にはこのような制限は掛けられていません。任意の SQL 文がいつでも発行可能 です。 select 文による結果を取得するには、fetchRow メソッドまたは fetchArray メソッドを使用します。 いずれも、 • • •

一回のコールにつき、1 行を取得する。 もう行が無いときは false を返す。 結果は配列として返す。

ところは同じですが、添字をどうするかに差異があります。 fetchRow メソッドでは数字(列順)を、fetchArray メソッドは列名を添字とします。 先ほどの例の場合であれば、 foreach($data = $xoopsDB->fetchRow($result)){ echo “>> “. $data[0] . “
\n”; }

$data = $xoopsDB->fetchArray($result){ echo “>> “. $data['uname'] . “
\n”; }

となります。どちらを使用するかは好みと行って良いでしょう。 また、select 文で一部分の行を抜き出す場合は、SQL 文に limit 句や、offset 句を記述しないで下 さい。これはデータベースによって構文が異なります。 query メソッド、queryF メソッドには • •

取得する行数 取得する行の開始位置

をオプション引数として引きわたすことが可能です。これらはそれぞれのデータベースに適した構 文を生成するのに使用されます。 ex) $xoopsDB->query(“select ... “, 10, 200); によって生成される(べき)SQL 文 MySQL

select ... limit 200, 10

PostgreSQL

select ... limit 10 offset 200

SQL 操作関連の主要メソッド一覧 メソッド

引数

返し値

動作

prefix

テーブル名

Prefix 付きテーブル名 prefix 付きテーブル名を返す

query

SQL 文

リザルトハンドラ

SQL 文を実行する

queryF

SQL 文

リザルトハンドラ

SQL 文を実行する

getRowsNum リザルトハンドラ 取得した行数 fetchRow

リザルトハンドラ 取得した行

備考 GET 時では select のみ可

取得した行数を返す 取得した行を 1 行取得する

添字は列の番号

取得した行を 1 行取得する

添字は列名

(もうないときは false) fetchArray

リザルトハンドラ 取得した行 (もうないときは false)

メニューの追加 モジュールのアップデート: 必要 メインメニューに、モジュール名が入った項目を出すには、xoops_version.php の$modversion ['hasMain']を 1 にする必要があります。 逆に不要な場合は 0 に設定してください。

$modversion['hasMain'] = 0 $modversion['hasMain'] = 1

サブメニューの追加 モジュールのアップデート: 必要 メニューにサブメニューを追加する場合も、xoops_version.php の編集が必要です。 （$modversion['hasMain'] = 1 であることが前提です） サブメニューは$modversion['sub']にエントリを追加することで追加します。 $modversion['sub'] = array( array('name' => "ページ(テンプレート無し)", 'url' => "skelton_page_without_template.php"), array('name' => "ページ(テンプレート有り)", 'url' => "skelton_page_with_template.php"), );

name にサブメニューに表示する項目名、 url にクリック時にアクセスする URL を記述します。 最後にモジュールのアップデートを実施してください。

ブロックを追加する モジュールの再インストール: 必要 （テンプレートの修正時のみの場合はモジュールのアップデートが必要） まず、コードファイルを blocks/ディレクトリに作成します。 ブロックの表示部分は関数として実装してください。 （一つのファイルで複数のブロックを定義することができます） 基本的に引数は必要ありません。 返値には、テンプレート変数名とその値のペアの配列を返します。(自動的にテンプレート変数に セットされます) function show_block() { return array("message" => "abc"); }

次にテンプレートを追加します。 テンプレートは templates/blocks/ディレクトリに作成してください。 ブロックのテンプレートは$modversion['templates']には追加しません。 代わりに$modversion['blocks']にブロックの情報のエントリを追加します。 $modversion['blocks'] = array( array(), //ダミー array('file' => 'skelton_block.php', 'name' => 'ブロック', 'description' => 'ブロック', 'show_func' => 'show_block', 'template' => 'skelton_block_template.html'), );

file にはブロックを定義したファイル名 name にはブロックの名前（ブロックを表示したときのタイトル） description にはブロックの説明 show_func にはブロックを定義したファイル内の関数名 template にはテンプレートファイル（templates/blocks 内） を記述してください。最後にモジュールの再インストールを実施します。 再インストール後、もう一度モジュールのアップデートをしてください。 注意: $modversion['blocks']の最初の array()は必要なダミーです。 削除しないで下さい。 管理者メニュー → ブロック管理で、ブロックが追加されていることを確認しください。

テーブルの作成 モジュールの再インストール: 必要 モジュールのインストール時に、テーブルを作成するための SQL 文を sql/mysql.sql ファイルに記 述します。(通常は create table, insert 文の羅列となります) このとき、テーブル名のプレフィクス（デフォルト: xoops_）は記述してはいけませんので注意してく ださい。 そして、この sql/mysql.sql の場所を宣言するため、xoops_version.php の$modversions['sqlfile'] ['mysql']にそのパスを指定します。(要アップデート) $modversion['sqlfile']['mysql'] = 'sql/mysql.sql';

次に、モジュールのアンインストール時に、テーブルを削除するためのテーブルの一覧を xoops_version.php の$modversion['tables']に指定します。 $modversion['tables'] = array ( 'skelton_table1', 'skelton_table2', 'skelton_table3', );

この場合もテーブル名にはプレフィクスを記述しませんので注意して下さい。

管理者メニューの追加 モジュールのアップデート: 必要 まず、xoops_version.php の$modversion['hadAdmin']を 1 にします。 これにより、管理者メニューにロゴのアイコンが表示されます。（要モジュールのアップデート）

$modversion['hadAdmin'] = 0

$modversion['hadAdmin'] =1

次に同じく xoops_version.php の$modversion['adminindex'], $modversion['adminmenu']にそれぞ れ'admin/index.php', 'admin/menu.php'を指定します。 $modversion['hasAdmin'] = 1; $modversion['adminindex'] = "admin/index.php"; $modversion['adminmenu'] = "admin/menu.php";

admin/menu.php には、ロゴをポイントしたときに表示されるメニューの一覧を記述します。 $adminmenu にエントリを追加してください。 $adminmenu = array( array('title' => '管理者メニュー 1', 'link' => 'admin/index.php?op=1'), array('title' => '管理者メニュー 2', 'link' => 'admin/index.php?op=2'), );

title には、メニューのタイトル link にはリンク先の URL を記述してください。 最後にモジュールのアップデートを行って下さい。

admin/index.php には、ロゴをクリックしたときにジャンプする（デフォルトの）管理者ページの URL を記述します。(次節参照)

管理者ページの追加 モジュールのアップデート: 不要 管理者ページは admin ディレクトリに作成します。テンプレートは使えません。 デフォルトのページは index.php です。 admin/index.php をコピー・編集してください。

include "../../../include/cp_header.php"; include "../header.php"; xoops_cp_header(); // ここに本文を書こう！ echo "管理者メニュー"; xoops_cp_footer();

管理者ページでは、xoops_cp_header()、 xoops_cp_footer()によりヘッダ、フッタの出力を行います。 そのためには、../../../include/cp_header.php を include する必要がありますので、忘れないようにし てください。 テンプレートは使用できませんので、html コードは直接 echo などで記述します。

以上