「開発:評定表レポートチュートリアル」の版間の差分

2010年10月23日 (土) 19:06時点における版

イントロダクション

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について取り上げてみます。

新しいファイル

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

   grade/report/[newreport]/lib.php

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 class methods

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

get_pref(): Given the name of a user preference (without grade_report_ prefix), locally saves then returns the value of that preference. If the preference has already been fetched before, the saved value is returned. If the preference is not set at the User level, the $CFG equivalent is given (site default).
set_pref(): Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value, the preference will be removed in favour of a higher-level preference ($CFG->$pref_name usually)
process_data(): Abstract method, needs to be implemented by child classes if they want to handle user form submissions on the report they want to handle user actions on the report
process_action(): Abstract method, needs to be implemented by child classes if they want to handle user actions on the report
get_grade_clean(): format grade using lang specific decimal point and thousand separator the result is suitable for printing on html page
format_grade(): Given a user input grade, format it to standard format i.e. no thousand separator, and . as decimal point
get_lang_string(): First checks the cached language strings, then returns match if found, or uses get_string(). Use this for any lang_strings in the grades.php file.
grade_to_percentage(): Computes then returns the percentage value of the grade value within the given range.
get_grade_letters(): Fetches and returns an array of grade letters indexed by their grade boundaries, as stored in preferences.
get_numusers(): Fetches and returns a count of all the users that will be shown on this page.
setup_groups(): Sets up this object's group variables, mainly to restrict the selection of users to display.
get_sort_arrow(): Returns an arrow icon inside an <a> tag, for the purpose of sorting a column.
get_module_link(): Builds and returns a HTML link to the grade or view page of the module given. If no itemmodule is given, only the name of the category/item is returned, no link.

Report child class

Assuming you are using flexitable, your child class needs the following variable and methods:

   $table : The flexitable that will hold the data

grade_report_[newreport]() : Constructor. You can set up anything here, but you must call the parent constructor with the 3 required params:

       parent::grade_report($COURSE->id, $gpr, $context);
       The $gpr and $context variables are normally set up in grade/report/[newreport]/index.php

setup_table() : Prepares the headers and attributes of the flexitable. Example used for the very simple overview report:

       // 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() : After setup_table(), gathers and enters the data in the table. Again, from the overview report:

       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() : Just does what its name says...

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

process_data() and process_action() : You can implement these two methods if you need to handle data and actions.

Set up the index.php file

Here is the simple example from the overview report (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);

結論

This short tutorial doesn't explain how to actually create a useful report. That part is essentially up to you, and there are no hard rules about how to do it. Instead, this tutorial explains how to setup a "stub" report, a basic framework with a set of tools and variables you can use to create a fully functional and essential report for your Moodle needs. Please share your report-building experiences and tribulations with the Moodle community through the forum.

@@ 93行目: / 93行目: @@
 === Grade_report class methods ===
-The grade_report class has the following methods which you can use, provided the right steps have been taken to initialise the object first:
+最初にオブジェクトを初期化する正しいステップが実行されるという条件で、grade_reportクラスには私たちが使用できる以下のメソッドがあります:
 ; get_pref()            : Given the name of a user preference (without grade_report_ prefix), locally saves then returns the value of that preference. If the preference has already been fetched before, the saved value is returned. If the preference is not set at the User level, the $CFG equivalent is given (site default).
 ; set_pref()            : Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value, the preference will be removed in favour of a higher-level preference ($CFG->$pref_name usually)

Documentation