開発:評定表レポートチュートリアル

イントロダクション

Moodle 1.9で新しく実装された素晴らしい機能のひとつにプラグインレポートのサポートがあります。いくつかのレポートはすでに実装されていますが、様々な種類の新しいレポートを素早く簡単に作成することができます。

このページはMoodle評定表に新しいレポートを作成するための簡単なチュートリアルです。最初のセクションではあなたのプラグインが検出され利用可能にするための基本的なセットアップのステップに焦点を合わせています。2番目のセクションでは考えられる実装例を説明しています。もちろん、あなたはこれらの提案を参考にせず自由に開発することができます。

このガイドを読む上での最もシンプルなレポート例はgrade/report/overviewです。

最小限度

これらすべてのステップには新しいファイルの作成が含まれますが、あなたの人生を楽にするため、すべてのケースにおいて既存のレポートをコピー&ペーストすることができます。

1. grade/report配下に新しいフォルダを作成してください。

   grade/report/[newreport]

2. 新しいレポートフォルダ配下に /dbサブフォルダを作成してください。

   grade/report/[newreport]/db

3. dbフォルダ内に下記のコンテンツを含むaccess.phpファイルを作成してください。必要に応じてケイパビリティを変更してください。

   grade/report/[newreport]/db/access.php
 
   <?php
   $gradereport_[newreport]_capabilities = array(
       'gradereport/[newreport]:view' => array(
           'riskbitmask' => RISK_PERSONAL,
           'captype' => 'read',
           'contextlevel' => CONTEXT_COURSE,
           'legacy' => array(
               'student' => CAP_ALLOW,
               'teacher' => CAP_ALLOW,
               'editingteacher' => CAP_ALLOW,
               'admin' => CAP_ALLOW
           )
       ),
   );
   ?>

4. 現在日付のversion.phpファイルを作成してください:

   grade/report/[newreport]/version.php
   <?php
   $plugin->version  = 2007081000;
   $plugin->requires = 2007081000;
   ?>

5. index.phpファイルを作成してください:

   grade/report/[newreport]/index.php

6. あなたのレポートの言語ファイルを作成してください。少なくともモジュール名、そして任意でケイパビリティのストリングを含んでください。

   grade/report/[newreport]/lang/en_utf8/gradereport_[newreport].php
   
   以下、ユーザレポートの言語ファイル例です:
   
   $string['modulename'] = 'ユーザレポート';
   $string['user:view'] = 'あなたオリジナルの評定レポートを表示します。';

あなたのレポートに新しいリンクを作成する必要はありません。あなたがすべてのステップに従った場合、レポートは自動的に検出され、評定表プラグインドロップダウンメニュー内に追加されます!

あなたが新しいレポートを作成するときに必要なものはこれですべてです! もちろん、通常、あなたは何かをするためにデータを取得して表示するためのコードを書くことでしょう。次のセクションではflexitableを使用する簡単なアプローチに関して話しましょう。

考え得るステップ 7

私はsettings.phpファイルを新しい「grade\report\[directory name]」ディレクトリに入れる必要もありました。このファイルが存在しないため、私には「Section Error!」というエラーメッセージが表示されていました。ファイルを「grade\report\[directory name]」ディレクトリに入れた後、エラーメッセージは表示されないようになりました。settings.phpファイルは空です。私はMoodle 1.9を使用しています。

考え得るステップ 8

レポートを複数ユーザが利用できるようにする場合、あなたのMoodleの管理セクションに移動して、通常のアップグレードと同じようにテーブルを更新する必要があります。その後、ロールの定義に移動して、あなたの設定が正しいかどうか確認してください。私はMoodle 1.9を使用しています。

grade_reportクラスを拡張する

あなたは自由に自分のやりかたでクラスを開発することができます。しかし、grade_repot内に配置されている既存のメソッドを使用することで、退屈なコードの繰り返しを避けることができます。私たちはシンプルなレポートにユーザレポート (grade_report_user class) 内にあるflextitableを使用します。このチュートリアルの残りの部分で、私たちはfulexitableについて取り上げてみます。

新しいファイル

1. lib.phpファイルを作成してください (または他のレポートからコピーしてください)。

   grade/report/[newreport]/lib.php

1. lib.phpはgrade_reportクラスのエクステンションを含み、下記のような名称となります。

   grade_report_[newreport]

Grade_reportクラス変数

あなたの子クラスのコンストラクタがgrade_reportのコンストラクタを使用する場合、grade_reportはあなたのクラスで使用できる下記の変数を作成します :

courseid

コンストラクタにより必要

gpr

オブジェクトをトラッキングする評定プラグイン戻り値 (Grade plugin return)、コンストラクタにより必要

context

コンストラクタにより必要

gtree

grade_treeは子クラスに生成する必要があります: ツリー全体にすべてのレポートが必要というわけではありません。

prefs

このレポートに関係するユーザプリファレンスの配列です。これらを容易に取得および設定できるよう、メソッドが提供されます。

gradebookroles

このレポートのロールです。$CFG->gradebookrolesから取得されます。

baseurl

姓名をソートするためのベースURIです (すべてのレポートで必要というわけではありません)。

pbarurl

ページングのベースURIです。

page

ページングのための現在のページです。ページングが必要な場合、コンストラクタを与える必要があります。

lang_strings

言語ストリングをキャッシュするための配列です (常にget_string() を使用すると長い時間を要します!)。このキャッシュをget_string() の代わりに使用するためのメソッドが提供されます。

currentgroup

表示されている現在のグループです。

group_selector

現在のグループを選択するためのHTML選択エレメントです。

groupsql

グループテーブルにリンク情報を追加するときに使用されるSQLフラグメントです。

groupwheresql

レポートを構築するため、このオブジェクトが使用するクエリに追加されるSQL制約 (constraint) です。

Grade_reportクラスメソッド

最初にオブジェクトを初期化する正しいステップが実行されるという条件で、grade_reportクラスには私たちが使用できる以下のメソッドがあります:

get_pref()

ユーザプリファレンス名を (grade_report_ prefixなしに) 取得します。ローカルに保存した後、プリファレンス値を返します。前にプリファレンスが取得されている場合、保存された値が返されます。プリファレンスがユーザユーザレベルで保存されていない場合、$CFGと等しい値 (サイトデフォルト) が渡されます。

set_pref()

ユーザプリファレンスの値を更新するため、set_user_preferences() を使用します。値に「default」が設定された場合、高いレベルのプリファレンス (通常、$CFG->$pref_name) を使用するため削除されます。

process_data()

抽象メソッドです。レポートでユーザフォームによる送信を処理したい場合、子クラスから実装される必要があります。

process_action()

抽象メソッドです。レポートでユーザの操作を処理したい場合、子クラスから実装される必要があります。

get_grade_clean()

言語特有の小数点および3桁区切り (thousand separator) を使用して評点をHTMLページに適した形でフォーマットします。

format_grade()

ユーザが入力した評点を標準書式でフォーマットします。例) 小数点に「.」を使用して、3桁区切り (thousand separator) に「,」を使用する。

get_lang_string()

最初にキャッシュされた言語ストリングを探します。合致する言語ストリングが見つかった場合、その言語ストリングを返します。または、get_string() を使用してください。これをgrades.phpファイル内のlang_stringsすべてに使用してください。

grade_to_percentage()

計算した後、与えられた範囲内における評定値のパーセンテージ値を返します。

get_grade_letters()

プリファレンスに保存されている、評定境界によりインデックス付けされた評定文字の配列を取得して返します。

get_numusers()

このページに表示されるユーザすべてをカウントして、カウント数を返します。

setup_groups()

表示するユーザの選択を制限することを主目的として、このオブジェクトのグループ変数をセットします。

get_sort_arrow()

カラムのソートを目的として、<a>タグの中の矢印アイコンを返します。

get_module_link()

評定へのリンクまたはモジュールの閲覧ページを構築した後、HTMLを返します。itemmoduleが与えられない場合、カテゴリ名/アイテムのみが返され、リンクは返されません。

レポート子クラス

あなたがFlexiTableを使用している場合、子クラスでは下記の変数およびメソッドが必要です:

   $table : データを保持するFlexiTable
   

• grade_report_[newreport]() : コンスタラクタです。あなたはどのようなものでもここに設定できますが、3個の必須パラメータを使って親コンストラクタをコールする必要があります:

       parent::grade_report($COURSE->id, $gpr, $context);
       通常、$gprおよび$context変数はgrade/report/[newreport]/index.phpにて設定されます。
   

• setup_table() : FlexiTableのヘッダおよび属性を準備します。例では非常に簡単なオーバービューレポートに使用されます:

       // setting up table headers
       $tablecolumns = array('coursename', 'grade', 'rank');
       $tableheaders = array($this->get_lang_string('coursename', 'grades'),
                             $this->get_lang_string('grade'),
                             $this->get_lang_string('rank', 'grades'));

       $this->table = new flexible_table('grade-report-overview-'.$this->user->id);

       $this->table->define_columns($tablecolumns);
       $this->table->define_headers($tableheaders);
       $this->table->define_baseurl($this->baseurl);

       $this->table->set_attribute('cellspacing', '0');
       $this->table->set_attribute('id', 'overview-grade');
       $this->table->set_attribute('class', 'boxaligncenter generaltable');

       $this->table->setup();
    

• fill_table() : setup_table()の後、データを収集してテーブルに入力します。再度、オーバービューレポートより:

       global $CFG;
       $numusers = $this->get_numusers();

       if ($courses = get_courses('all', null, 'c.id, c.shortname')) {
           foreach ($courses as $course) {
               // Get course grade_item
               $grade_item_id = get_field('grade_items', 'id', 'itemtype', 
                                          'course', 'courseid', $course->id);

               // Get the grade
               $finalgrade = get_field('grade_grades', 'finalgrade', 'itemid', 
                                       $grade_item_id, 'userid', $this->user->id);

               /// prints rank
               if ($finalgrade) {
                   /// find the number of users with a higher grade
                   $sql = "SELECT COUNT(DISTINCT(userid))
                           FROM {$CFG->prefix}grade_grades
                           WHERE finalgrade > $finalgrade
                           AND itemid = $grade_item_id";
                   $rank = count_records_sql($sql) + 1;

                   $rankdata = "$rank/$numusers";
               } else {
                   // no grade, no rank
                   $rankdata = "-";
               }

               $this->table->add_data(array($course->shortname, $finalgrade, $rankdata));
           }

           return true;
       } else {
           notify(get_string('nocourses', 'grades'));
           return false;
       }

• print_table() : 名称通りのことが実行されます ...

       ob_start();
       $this->table->print_html();
       $html = ob_get_clean();
       if ($return) {
           return $html;
       } else {
           echo $html;
       }
       

• process_data() および process_action() : あなたがデータおよび操作を処理したい場合、これら2つのメソッドを実装することができます。

index.phpファイルをセットアップする

以下、オーバービューレポート (grade/report/overview) からのシンプルな例です。

   require_once '../../../config.php';
   require_once $CFG->libdir.'/gradelib.php';
   require_once $CFG->dirroot.'/grade/lib.php';
   require_once $CFG->dirroot.'/grade/report/overview/lib.php';

   $courseid = optional_param('id', $COURSE->id, PARAM_INT);
   $userid   = optional_param('userid', $USER->id, PARAM_INT);

   /// basic access checks
   if (!$course = get_record('course', 'id', $courseid)) {
       print_error('nocourseid');
   }
   require_login($course);

   if (!$user = get_complete_user_data('id', $userid)) {
       error("Incorrect userid");
   }

   $context     = get_context_instance(CONTEXT_COURSE, $course->id);
   $usercontext = get_context_instance(CONTEXT_USER, $user->id);
   require_capability('gradereport/overview:view', $context);

   $access = true;
   if (has_capability('moodle/grade:viewall', $context)) {
       //ok - can view all course grades

   } else if ($user->id == $USER->id and has_capability('moodle/grade:view', $context) and $course->showgrades) {
       //ok - can view own grades

   } else if (has_capability('moodle/grade:viewall', $usercontext) and $course->showgrades) {
       // ok - can view grades of this user- parent most probably

   } else {
       $acces = false;
   }

   /// return tracking object
   $gpr = new grade_plugin_return(array('type'=>'report', 'plugin'=>'overview', 'courseid'=>$course->id, 'userid'=>$userid));

   /// last selected report session tracking
   if (!isset($USER->grade_last_report)) {
       $USER->grade_last_report = array();
   }
   $USER->grade_last_report[$course->id] = 'overview';

   /// Build navigation
   $strgrades  = get_string('grades');
   $reportname = get_string('modulename', 'gradereport_overview');

   $navigation = grade_build_nav(__FILE__, $reportname, $course->id);

   /// Print header
   print_header_simple($strgrades.': '.$reportname, ': '.$strgrades, $navigation,
                       , , true, , navmenu($course));

   /// Print the plugin selector at the top
   print_grade_plugin_selector($course->id, 'report', 'overview');

   if ($access) {

       //first make sure we have proper final grades - this must be done before constructing of the grade tree
       grade_regrade_final_grades($course->id);

       // Create a report instance
       $report = new grade_report_overview($userid, $gpr, $context);

       $gradetotal = 0;
       $gradesum = 0;

       // print the page
       print_heading(get_string('modulename', 'gradereport_overview'). ' - '.fullname($report->user));

       if ($report->fill_table()) {
           echo $report->print_table(true);
       }

   } else {
       // no access to grades!
       echo "Can not view grades."; //TODO: localize
   }
   print_footer($course);

結論

この短いチュートリアルでは「有益な」レポートの作成方法を説明しているわけではありません。その部分は基本的にあなた次第であり、レポートを作成するための難しいルールはありません。代わりにこのチュートリアルでは、あなたのMoodleでの必要性に応じて作成する、完全に機能的かつ重要なレポートを作成するための基本的なフレームワーク、つまり「スタブ」レポートに関する設定方法を説明しています。あなたのレポート開発および経験した困難を、フォーラムを通してMoodleコミュニティと共有してください。

関連情報

• 評定表開発アイデア フォーラムディスカッション - 英語
• Using Moodle Moodleの新しい評定表 フォーラムディスカッション - 英語
• 開発: 評定