開発:評定表レポートチュートリアル
作成中です - Mitsuhiro Yoshida
イントロダクション
Moodle 1.9で新しく実装された素晴らしい機能のひとつにプラグインレポートのサポートがあります。いくつかのレポートはすでに実装されていますが、様々な種類の新しいレポートを素早く簡単に作成することができます。
このページはMoodle評定表に新しいレポートを作成するための簡単なチュートリアルです。最初のセクションはあなたのプラグインが検出され利用可能にするための基本的なセットアップのステップに焦点を合わせています。2番目のセクションでは考えられる実装例を説明しています。しあkし、あなたはこれらの提案を参考にせず自由に開発することができます。
このガイドを読む上で、最もシンプルなレポート例は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()
- ユーザプリファレンス名を (grade_report_ prefixなしに) 取得します。ローカルに保存した後、プリファレンス値を返します。前にプリファレンスが取得されている場合、保存された値が返されます。プリファレンスがユーザユーザレベルで保存されていない場合、$CFGと等しい値 (サイトデフォルト) が渡されます。
- set_pref()
- ユーザプリファレンスの値を更新するため、set_user_preferences() を使用します。値に「default」が設定された場合、高いレベルのプリファレンス (通常、$CFG->$pref_name) を使用するため削除されます。
- process_data()
- 抽象メソッドです。レポートでユーザフォームによる送信を処理したい場合、子クラスから実装される必要があります。
- process_action()
- 抽象メソッドです。レポートでユーザの操作を処理したい場合、子クラスから実装される必要があります。
- 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.
関連情報
- Gradebook Development ideas forum discussion
- Using Moodle New gradebook for Moodle forum discussion
- Development:Grades