活動モジュール (Dev docs)

重要: このページの内容は更新され、新しいMoodle Developer Resourcesに移行されました。このページに含まれる情報は、もはや最新であるとみなされるべきではありません。 このページを新サイトで閲覧する そして より多くのコンテンツを新サイトに移行するために協力する というのはいかがでしょうか！

（このページは現在翻訳中です。）

導入

活動モジュールは /mod ディレクトリに存在します。

各モジュールは別々のサブディレクトリにあり、いくつかの '必須ファイル' と開発者が使用するその他のファイルから構成されています。下の画像は、証明書モジュールのファイル構造の一例です。なお、本書で <modname> と表記されている場合は、モジュール名に置き換えてください。

以下は、証明書プラグインのファイル構成例です。

標準ファイルとその機能

Moodleには、いくつかの重要なファイルがあります。これらのファイルは、あなたのモジュールをインストールし、Moodleシステムに統合するために使用されます。各ファイルには特定の機能があり、一部のファイルは必要なく、その機能を使用する場合にのみ作成されます。以下は、よく使われるファイルのリストです。

バックアップフォルダ

これは、コースのバックアップまたはリストアが実行されたときに、モジュールがどのように動作するかを定義するファイルを配置する場所です。コースをリストアする際、再度入力したくない特定のモジュールの情報をデータベースに追加した場合、バックアップ中に何を保存し、どのようにMoodleバックアップから情報をリストアするかを定義する場所です。

詳しくは、開発者向けバックアップ2.0 と 開発者向けバックアップ2.0 をご覧ください。

DBフォルダ

access.php

ここでは、プラグインがどのような機能を作成するかを定義します。なお、プラグインのインストール後にこのファイルに新しい機能を追加する場合は、version.phpファイル（後述）のバージョン番号を上げてインストールさせる必要があります。

ファイルの例は以下の通りです -

$capabilities = array(

    'mod/certificate:addinstance' => array(
        'riskbitmask' => RISK_XSS,
        'captype' => 'write',
        'contextlevel' => CONTEXT_COURSE,
        'archetypes' => array(
            'editingteacher' => CAP_ALLOW,
            'manager' => CAP_ALLOW
        ),
        'clonepermissionsfrom' => 'moodle/course:manageactivities'
    ),
);

Moodle 2.3では、すべてのコアモジュールに 'addinstance' という新しい機能が追加されました。Moodleは 'mod/<modname>:addinstance' を検索してこのケイパビリティを探し、もしそれが作成されない場合、ユーザがこのケイパビリティを持っていると仮定し、ケイパビリティが欠けているというデバッグメッセージが表示されます。このような事態を避けるために、モジュールにこれを追加しておくとよいでしょう。

また、すべての活動モジュールが、可視性を制御するための 'mod/<modname>:view' ケイパビリティを提供することも推奨します。 (参照 MDL-40854)

一貫性を保ち、教師が使いやすいように、

mod/<modname>:view

のケイパビリティを持つ以下のアーキタイプを使うことが推奨されます:

'mod/MODULENAME:view' => array(
    'captype' => 'read',
    'contextlevel' => CONTEXT_MODULE,
    'archetypes' => array(
        'guest' => CAP_ALLOW,
        'student' => CAP_ALLOW,
        'teacher' => CAP_ALLOW,
        'editingteacher' => CAP_ALLOW,
        'manager' => CAP_ALLOW
    )
)

ケイパビリティ配列の各属性の意味については、NEWMODULE ケイパビリティを追加するを参照してください。

events.php

イベント監視のためのオブザーバを設定する。

オブザーバを設置したら、次はMoodleにオブザーバの存在を知らせる必要があります。私たちは、プラグインevents.phpにエントリを追加することにより、これを行います。

例 - mod/quiz/db/events.php

$observers = [
    [
        'eventname' => '\mod_quiz\event\attempt_submitted',
        'includefile' => '/mod/quiz/locallib.php',
        'callback' => 'quiz_attempt_submitted_handler',
        'internal' => false,
    ],
];

詳しくはイベント APIのページをご覧ください。

install.xml

このファイルは、あなたのモジュールのインストール時に使用されます; これは関連するデータベーステーブルを定義しています。各モジュールについて、データベースはモジュール自身と同じ名前のメインテーブルを持つ必要があります。さらに、他のデータベーステーブルを定義することもできます。XMLファイルを作成するには、XMLDBエディタをご覧ください。XMLファイルでは、テーブル名はconfig.phpの接頭辞なしで記載されていますが、これはテーブル作成時に自動的に使用されるため、指定する必要はないことに注意してください。

XMLDBエディタが生成するファイルの例を以下に示します - これはテーブル certificate と certificate_issues の構造が含まれています:

<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
  <TABLES>
    <TABLE NAME="certificate" COMMENT="Defines certificates">
      <FIELDS>
        <FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true"/>
        <FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" />
        <FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" />
        <FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" />
        <FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" />
        <FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" />
        <FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" />
        <FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" />
        <FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
      </FIELDS>
      <KEYS>
        <KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
      </KEYS>
    </TABLE>
    <TABLE NAME="certificate_issues" COMMENT="Info about issued certificates">
      <FIELDS>
        <FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" />
        <FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
        <FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" />
      </FIELDS>
      <KEYS>
        <KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" />
        <KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" />
      </KEYS>
    </TABLE>
  </TABLES>
</XMLDB>

Moodleコアがすべての活動モジュールのメインテーブルに存在することを期待する (または、事実上の標準となった) フィールドがいくつか存在します:

フィールド名	プロパティ	備考
id	INT(10), auto sequence	テーブルのプライマリキー (Moodleの他のテーブルと同様)
course	INT(10), foreign key to the course table	この活動が含まれるコースのID
name	CHAR(255)	活動モジュールのインスタンスの名前を保持する
timemodified	INT(10)	インスタンスが最後に変更されたときのタイムスタンプ
intro	TEXT	活動の説明を保持する標準フィールド（FEATURE_MOD_INTROを参照）
introformat	INT(4)	イントロフィールドのテキストの形式を指定する

upgrade.php

このファイルは、モジュールを最新のバージョンに合わせるためのアップグレードを処理します。モジュールを作成し、自分のサイト（および他のサイト）で広範囲に使用した後、モジュールの機能を拡張したいと思うかもしれません。証明書の例では、発行された証明書ごとに固有のコードを生成し、設定が選択された場合に表示することが提案されました。これは、証明書の作成者が証明書にコードを表示することを選択したかどうかを格納するフィールドと、各学生の実際のコードを格納するフィールドの2つの新しいデータベースが必要です。ここで、upgrade.phpスクリプトが使われるようになります。install.xmlファイルは、モジュールが最初にインストールされたときに一度だけ実行されます。したがって、このファイルにこれら2つの余分な列を追加しても、すでにモジュールをインストールしたユーザのデータベース構造を変更することはありません。そこで、このアップグレードを行うには、次の3つのことを行う必要があります。

1. install.xmlファイルに新しいカラムを追加し、この時点以降にモジュールをインストールするユーザに新しいテーブル構造を提供するようにします。
2. upgrade.phpファイルの説明を追加します。
3. version.phpファイルのバージョン番号を更新します。

この例では、データベースに2つの新しいカラムを追加するだけなので、XMLDBエディタを使用してinstall.xmlファイルを変更し、アップグレードパスを作成することができます。

upgrade.phpファイルの例は次の通りです -

function xmldb_certificate_upgrade($oldversion=0) {
    if ($oldversion < 2012091800) {
        // certificateテーブルに新規フィールドを追加する
        $table = new xmldb_table('certificate');
        $field = new xmldb_field('showcode');
        $field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
        if (!$dbman->field_exists($table, $field)) {
            $dbman->add_field($table, $field);
        }
        // certificateテーブルに新規フィールドを追加する
        $table = new xmldb_table('certificate_issues');
        $field = new xmldb_field('code');
        $field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
        if (!$dbman->field_exists($table, $field)) {
            $dbman->add_field($table, $field);
        }

        // 証明書のセーブポイントに到達した
        upgrade_mod_savepoint(true, 2012091800, 'certificate');
    }
}

あなたがversion.phpモジュールでバージョンを変更した場合、Moodleは何かが必要であるかどうかを確認するために、常に調べます。データベースに保存されているバージョンは、この場合、変数 $oldversion として xmldb_<modname>_upgrade 関数に渡されます。この例では、初期バージョンが2012091600であったとします。これは2012091800（version.phpファイルに入れた新しい値）より小さいので、if文のコードを実行し、データベースに保存されているバージョンを更新します。このif文は二度と実行されないことになります。これに関する詳細な情報は、アップグレードAPIを参照してください。

mobile.php

Moodle 3.1 の新機能

ここでは、プラグインに含まれるMoodle Mobile Remoteアドオンを定義します。

Moodleモバイルリモートアドオンは、ユーザがアプリ上でプラグインにアクセスした際に読み込まれる、モバイルアプリ版のプラグインです。

複数のモバイルアドオンを搭載することができます。各アドオンには、固有の名前を指定する必要があります (固有の名前でなければならないため、一般的な名前は使用しないことをお勧めします。アドオンがサポートするMoodleプラグインのコンポーネント名を使用するのが最良の方法です)。

名前に空白を入れることはできません。また、大文字を使わないことをお勧めします。

ここで参照する各アドオンは、javascript/html/css のコードを含む zip ファイルとして plugin mobile/ フォルダに含める必要があります。zip の名前は、アドオン名と同じにする必要があります。

次の例でのファイル名のパス: mobile/mod_certificate.zip

$addons = array(
    "mod_certificate" => array(
       "dependencies" => array("pdfbuilder")
    ),
);

同じファイルに複数のアドオンがある場合（または異なるプラグインにある場合）、依存関係をここで指定することが可能です。

モバイルアドオンの開発に関する詳細情報は、Moodle Mobile Remoteアドオンをご覧ください。

Langフォルダ

プラグインで使用する文字列を格納する場所です。各言語には、モジュールで使用するために作成する必要がある特定のフォルダがあります。今回は英語を使うことにします（残念ながら私が知っているのはこれだけなので）。lang フォルダ内に en というフォルダが作られ、その中に <modname>.php という文字列の翻訳を一覧表示するファイルがあります。例えば、あなたのモジュールに「ユーザ設定」という設定があるとします。この用語をフォームにハードコーディングするのではなく、あなたのMoodleサイトで使用されている言語に応じて、適切な文字列を取得するプレースホルダを使用します。モジュールには 'pluginname' という必須プレースホルダがあり、Moodleがこのモジュールをコースおよびその他の様々なページに追加するオプションとしてリストする際に使用します。Moodleの標準に従うため、あなたは文字列をプレースホルダ名でアルファベット順に並べる必要があります。

$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';

フランス語の翻訳を追加したい場合は、fr というフォルダを作成し、そこに <modname>.php というファイルを追加します。

$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';

ここで、文字列 'User preferences' を使用する場合、代わりに Moodle の関数 get_string を使用します。これは、使用されている言語に応じて、適切な文字列を取得します。

get_string('userpreferences', 'certificate');

Pixフォルダ

ここでは、あなたのモジュール名の隣に表示させたいアイコンを保存します。ファイル名は icon.gif とし、16 * 16 の解像度で表示されるようにします。このフォルダには、他にも使用する写真を保存しておくことができますので、ご自由にお使いください。

アップデート: 2.4以降、すべてのコアMoodleアクティビティでSVGファイルが導入されました。これに関する詳細は、Moodleのアイコン 2.4を参照してください。

lib.php

lib.phpでオーバーライド可能な関数の一覧は、NEWMODULEドキュメンテーション#lib.phpに記載されています。 必須なものは以下の通りです。

function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);

<modname>_add_instance 関数は、最初に活動を作成して送信をクリックすると、mod_form.php ファイル（後述）からオブジェクトとして変数を渡されます。ここで、そのデータを受け取り、好きなように加工して、望むならデータベースに挿入することができます。これはモジュールインスタンスが最初に作成されたときに一度だけ呼び出されるので、ここに活動を追加するロジックを配置する必要があります。

<modname>_update_instance 関数は、活動を更新して送信をクリックするたびに、mod_form.php ファイルからオブジェクトとして変数を渡されます。編集するインスタンスの id が属性インスタンスとして渡され、そのインスタンスのデータベース内の既存の値を編集するために使用することができます。

<modname>_delete_instance 関数には、モジュールの id が渡され、その id に関連するデータベーステーブルからレコードを削除するために使用することができます。例えば、証明書モジュールでは、証明書テーブルの id が渡され、データベースから証明書を削除し、この証明書の発行とファイルシステム上の関連ファイルを削除するために使用されます。Moodleコースでごみ箱が有効になっている場合、あなたの活動は削除のためにキューに入れられ、スケジュールされた cron タスクが実行されたときに削除されます。活動削除時に delete_instance 関数がすぐに実行されるように、コースのごみ箱を無効にしてください。

mod_form.php

このファイルは、コースにモジュールを追加/編集する際に使用されます。モジュールのインスタンスを作成/インストールするためのフォームに表示される要素が含まれています。ファイル内のクラスは mod_<modname>_mod_form という名前にします。

if (!defined('MOODLE_INTERNAL')) {
    die('Direct access to this script is forbidden.');    ///  Moodleのページに含まれている必要があります
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

    function definition() {
        global $CFG, $DB, $OUTPUT;

        $mform =& $this->_form;

        $mform->addElement('text', 'name', get_string('certificatename', 'certificate'), array('size'=>'64'));
        $mform->setType('name', PARAM_TEXT);
        $mform->addRule('name', null, 'required', null, 'client');

        $ynoptions = array(0 => get_string('no'),
                           1 => get_string('yes'));
        $mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
        $mform->setDefault('usecode', 0);
        $mform->addHelpButton('usecode', 'usecode', 'certificate');

        $this->standard_coursemodule_elements();

        $this->add_action_buttons();
    }
}

上記の例は、完全なファイルを含んでいるわけではありませんが、アイデアを提供するのに十分なものです。まず、必須項目である 'name' というテキスト要素を作成します。これは明らかにインスタンスの名前です。次に、ユーザが証明書を受け取ったときに発行された固有のコードを表示するかどうかを保存する別の要素を作成し、デフォルト値を 0 とし、この設定が何をするのかを説明するヘルプボタンを表示しました。関数 standard_coursemodule_elements は、条件フィールドのようなすべてのモジュールに共通する要素を追加するものです。add_action_buttons 関数は、フォームに送信ボタンとキャンセルボタンを追加します。このデータは、新しいインスタンスを追加するか、現在のインスタンスを更新するかによって、<modname>_add_instance または <modname>_update_instance のいずれかに渡されます。また、Moodleの他のフォームと同様に、このフォームにバリデーションを追加することができます。Moodleでフォームを作成する方法の詳細については、フォーム APIをご覧ください。

index.php

このページはコースIDがこのスクリプトに渡され、特定のコースに存在するあなたのモジュールのすべてのインスタンスをリストアップする際にMoodleによって使用されます。ページの冒頭には、以下の内容を記載してください -

require_once('../../config.php');

$id = required_param('id', PARAM_INT);           // コース ID

// 指定されたコースが有効であることを確認する
if (!$course = $DB->get_record('course', array('id'=> $id))) {
    print_error('Course ID is incorrect');
}

その後、インスタンスのリストを自由に表示することができます。

view.php

コースがページレイアウトおよび活動を表示する場合、view.php スクリプトを使用してそれらを表示するためのリンクを生成します。したがって、リンクは <wwwrootofyoursite>/mod/<modname>/view.php?id=4（4はコースモジュールID）のように表示されます。証明書の例では、view.php ページの冒頭は次のようになります -

require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT);    // コースモジュール ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
    print_error('Course Module ID was incorrect'); // 注: print_error の使用は無効で、lang 文字列の id でなければなりません
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
    print_error('course is misconfigured');  // 注: 上記と同様
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
    print_error('course module is incorrect'); // 注: 上記と同様
}

コースモジュールIDはこのスクリプトに渡され、$id として設定されます。このスクリプトはコースデータおよび証明書テーブルから情報を取得するために使用され、後で好きなように使用することができます。

あなたが Moodle 2.8 以上を使用している場合、新しい機能を使用して、この大部分を実現する良い方法があります:

require('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT);
list ($course, $cm) = get_course_and_cm_from_cmid($id, 'certificate');
$certificate = $DB->get_record('certificate', array('id'=> $cm->instance), '*', MUST_EXIST);

version.php

version.php ファイルはあなたのモジュールのバージョン、およびモジュールが必要とするMoodleのバージョンなどの属性を記録します。属性の全リストはversion.phpをご覧ください。

関連項目

• NEWMODULEドキュメンテーション (Dev docs)