開発:ポートフォリオAPI
Moodle 2.0 このページでは、将来の機能に関する仕様を記述しています。現在、Moodle 2.0に取り掛かっています。また、この仕様に関するページは作成中です。
オーバービュー
ポートフォリオAPIは、多くの外部ドキュメントリポジトリシステムに関して、私たちが簡単にファイルを登録できるよう、すべてのMoodleコードが利用できるインターフェースのコアセットです。
ポートフォリオは、一般的に書き込み専用 (WRITE-ONLY) であることを憶えておくことは重要です。私たちがMoodleで実行するすべてのことは、何かを掴んで、どこかに押し出すことです。ファイルの管理、さらなる結合/反映は、ポートフォリオシステムから提供されるネイティブなインターフェースを通して実現されます。リポジトリからのファイルの読み取りは、リポジトリAPIによって処理されます。
典型的なユーザのストーリー:
- ポートフォリオが有効にされた場合、Moodleの主要なコンテンツには小さな「保存」ボタンが表示されます。
- ユーザが「保存」ボタンをクリックします。
- ユーザは、設定済みポートフォリオのリストからポートフォリオを選択することができます (ポートフォリオが1つのみ設定されている場合、このステップはスキップされます)。
- 選択したコンテンツのフォーマット (例 PDF、IMS LD、HTML、XML ...) を定義するよう、ユーザは求められます。
- 選択したコンテンツと同時に送信されるよう、ユーザはいくつかのメタデータの定義を求められます (いくつかは自動的に生成されます)。
- コンテンツおよびメタデータが外部ポートフォリオシステムにコピーされます。
- ユーザは「あなたが離れたページに戻る」または「ポートフォリオへ移動する」オプションを選択することができます。
これは、学生と同じく、教師にとっても有用です。
フォーマットは、ボタンのコンテクストおよび外部ポートフォリオのタイプによって変わります。例えば、ユーザはコースページの「保存」ボタンを使用して、IMS LDまたはMoodleバックアップの形式ですべてのコースを取得することができます。しかし、この「保存」ボタンは、フォーラムページにはありません。
アーキテクチャー
では、どのように動作するか説明します:
プラグインおよびライブラリ
プラグインには1つのタイプがあります。
- Portfolio (例 Mahara/Elgg/OSP/Facebook/Download) - これは、portfolio/type/xxxのようになります。
トランスポートレイヤー (例 mnet/http/scp/cp/dav等) またはクライアント (例 box.net/flickr) は、リポジトリおよびポートフォリオの両者を共有するため、ライブラリとして作成されます。
例えば、IMS、Moodleネイティブ、Maharaネイティブ、PDF、暗号化PDFのように、プラグインがサポートする異なるフォーマットがあります (また、一部のMoodleエクスポートコンテンツも同様にサポートされます)。これらのフォーマットは、サポートされるための良いライブラリを持つことになります。
管理者 (Admin)
いくつかのプラグインが複数インスタンスを持てるようにすることは重要です。新しいプラグインを追加する手順は、下記のとおりです:
- 管理者がポートフォリオ設定に移動します。
- 利用可能なポートフォリオ一覧からポートフォリオを選択して、「外部ポートフォリオを追加する」をクリックします (すでにインスタンスが存在して、プラグインが複数インスタンスをサポートしていない場合、いくつかのポートフォリオは、無効にされています)。
- プラグインを設定します - 使用するトランスポートおよびコンテンツタイプを選択します。複数インスタンスがサポートおよびインストールされている場合、URI、認証キー等を設定します。
- パーミッションを設定します (恐らく) - ロールによって処理されます。
多くの場合、直接認証するためにユーザのみ必要とするため、この設定は、すべてのタイプのポートフォリオに必要というわけではありません。また、それぞれのユーザの設定を保持する場合、私たちはユーザプリファレンスのみ使用します。
エクスポート
- ユーザは、新しいportfolio_add_button()をコールするページを閲覧しています。ここでは、設定されたポートフォリオプラグインのインスタンスがあるかどうか確認して、(恐らく) ポートフォリオに関連するパーミッション、それからユーザのポートフォリオ設定がどのようになっているか確認します。そして、単一の「ポートフォリオを追加する」ボタン、または追加ボタンと同時に利用可能なシステムのドロップダウンメニューを表示します。
- このボタンがクリックされた場合、責任範囲のポストデータ (活動モジュールまたはコース、ブログ等)、コールバックファイル、コールバック引数、同じく任意でコンテンツタイプに関する情報を含んで、ユーザはportfolio/add.phpにリダイレクトされます。
- このページでは、アイテムに関するメタデータを入力および設定オプションのフォームがユーザに提供されます。この時点で、(プラグインおよびモジュールがサポートする共通部分に基づいて) 複数のフォーマットをエクスポートに利用できる場合、どのフォーマットを使用するかユーザが選択できます。プラグインおよびモジュール共に、このページのmform要素をエクスポートすることができます。この時点で、ユーザはデータを送信、待機 (時間が掛かる旨の警告を含む)、大きい場合は処理のためキューに入れる選択ができます。これは、エクスポートされるデータのサイズによって決定されます。
- ユーザがフォームを送信した場合、「承認」および「キャンセル」ボタンと共に、送信しようとしているファイルの概要が表示されます。「承認」が次のステップへ進むのに対して、「キャンセル」では、リクエストをキャンセルして一時データを削除した後、ユーザを元の場所に戻します。
- どのような場面でも、ポートフォリオプラグインは、手続き (step) をコントロールする必要があります。例えば、facebookまたはflickrは、最初にユーザのログインが必要であり、それらのAPIにアクセスするため、Moodleを承認する必要があります。
- ユーザが送信予定ファイルの概要を承認した場合、「portfolio_send」イベントが起動 (trigger) されます。この時点で、以下2つのうちの1つが発生します。
- ユーザが待つことを選択した場合、「インスタント」イベントが実行され、呼び出し側が再度コントロールを取得した時点で、ユーザにステータスを表示します。
- ユーザがキューを選択した場合、遅延イベントが実行され、ユーザに通知されます。
- ユーザには、ポートフォリオを続けるか、元の場所に戻るかのオプションが与えられます。
- イベントが処理 (cron経由またはインスタントイベント) された場合、次のことが発生します:
- イベントハンドラが起動されます。これは、転送を再起動し、コントロールを呼び出し側に委ねます。そして、ポートフォリオは、パッケージ転送の準備をします。
- これが完了した場合、私たちはコントロールをイベントハンドラに戻します。また、イベントハンドラが「インスタント」の場合、呼び出し側にtrueを返します。
ストレージ
明らかにこの処理中、ウェブサーバ間のリクエスト、またユーザインプットおよびイベントハンドリング間で状態が分からなくなります。すべてのデータは、連続する (そしてbase64エンコードされた) 送信者、プラグイン、呼び出し側オブジェクトの形でデータベースに保存されます。
また、ファイルはエクスポートの準備段階で書き込まれます。そして、新しいファイルAPIを使用して、特別ポートフォリオエリアに保存されます。
アクセス/パーミッション
- ボタンを表示する前、呼び出しコードは必要なパーミッションチェックを実行する必要があります。しかし、エクスポート中、ポートフォリオコードは、呼び出し側オブジェクトのcheck_permissions関数をコールします。
- 是非とも、いくつかのロールでポートフォリオインスタンスを利用できるようにしたかったのですが、この考え方は止めることにしました。
イベントAPI
キューに入れられたイベントを処理するため、ポートフォリオのコードは、イベントAPIを使用します。また、これには、転送オブジェクトの復活および転送再開のため、1つのエントリポイントがあります。さらに、Moodleのほかの部分と同じように、ポートフォリオプラグインはイベントを予約することができます。
テクニカル
Abstract portfolioベースクラス: portfolio_plugin_base
多くの抽象関数プラグインおよびプラグインが任意にオーバーライドできる関数と共に、自身の関数を使用した、いくつかの基本的な機能の混合提供を実装すべきです。
関連情報: あなたが新しいポートフォリオプラグインを作成する場合にする必要のあることに関するインストラクションと同様に、あなたがオーバーライド「すべき/できる/してはならない」完全なリストは、開発:ポートフォリオプラグインを書くをご覧ください。
Abstract Callerベースクラス : portfolio_caller_base
Moodleのどこかに「ポートフォリオを追加する」ボタンを追加する場合、いつでもこれをサブクラスにする必要があります。
関連情報: portfolio_add_buttonのコールの方法と同様に、あなたがオーバーライド「すべき/できる/してはならない」完全なリストは、開発:ページにポートフォリオボタンを追加するをご覧ください。
データベーステーブル
インストールされるプラグインの実際の情報は、mdl_config_pluginに保存されます。
加えて、プラグインごとに1つのconfigをセットするのではなく、私たちはプラグインのインスタンスを設定していますので、mdl_config_pluginは使用しません。代わりに一連のテーブルを使用します:
portfolio_instance:
| フィールド | データタイプ | コメント |
| id | integer | 連続 |
| plugin | varchar(50) | プラグイン名 (直接、ポートフォリオ/タイプに合致します) |
| name | varchar(255) | プラグインインスタンス名 |
| visible | smallint | 0 または 1 |
portfolio_instance_config:
| フィールド | データタイプ | コメント |
| id | integer | 連続 |
| instance | integer | (擬似的な) portfolio_instanceのfk (field key フィールドキー) |
| name | varchar(255) | config名 |
| value | text | config値 |
portfolio_instance_user:
| フィールド | データタイプ | コメント |
| id | integer | 連続 |
| instance | integer | (擬似的な) mdl_portfolio_instanceのfk (field key フィールドキー) |
| userid | integer | (擬似的な) mdl_userのfk (field key フィールドキー) |
| name | varchar(255) | config名 |
| value | text | config値 |
portfolio_log:
| フィールド | データタイプ | コメント |
| id | integer | 連続 |
| userid | integer | (擬似的な) mdl_userのfk (field key フィールドキー) |
| time | integer | 転送に関するUnixタイムスタンプ |
| portfolio | integer | (擬似的な) mdl_portfolio_instanceのfk (field key フィールドキー) |
| caller_class | varchar(150) | 呼び出し側クラス名 (表示情報が重複する場合、使用されます) |
| caller_file | varchar(255) | caller_class定義を含むファイル |
| caller_sha1 | varchar(255) | エクスポートのsha1情報 |
portfolio_tempdata
| フィールド | データタイプ | コメント |
| id | integer | 連続 |
| data | text | エクスポートデータの連続表示 |
| expirytime | integer | レコードおよび関連ファイルが削除される、このデータ (および転送 ) の有効期限 |
| userid | integer | (擬似的な) mdl_userのfk (field key フィールドキー) |
portfolio/type/xxx/内部に「db/install.xml」および「db/upgrade.php」を作成することで、すべてのプラグインは、独自のデータベーステーブルを必要に応じて実装することができます。詳細は、開発:ポートフォリオプラグインを書くをご覧ください。
ポートフォリオプラグイン
- mahara (最初に実装される予定です)
- download (最初に実装される予定です)
- box.net (最初に実装される予定です)
- flickr (このコードは、Nicoが書いていますが、まだ完了していないようです)
- googledocs (このコードは、DanPが書いていると思います)
トランスポートタイプおよびフォーマットは、使用するポートフォリオおよびリポジトリタイプ両方の複数プラグインに関する、共有ロケーションで探すことができるべきです。しかし、Moodleが探すことのできる、複数ロケーションに配置するプラグインタイプは、それぞれのロケーション内で1つに限定した方が良いかもしれません (例 Maharaネイティブフォーマットは、Maharaポートフォリオプラグイン内にありますが、PDFフォーマットは共有ライブラリにあります)。
予定される転送タイプ
- mnet (Maharaポートフォリオプラグインの一部として、最初に実装される予定です)
- download (send_file_* 関数を使用します)
- http
- filesystem (local/nfs/sambaのようにできます) (cp)
- ssh based (例 scp - sshキーを上手に処理していますので、elggブロックコードを調査して、再利用したいと思います)
- webdav
- open social? (http://code.google.com/apis/opensocial/)
予定されるエクスポートフォーマット
(ここで留意すべき点は、私たちは初期の実装で必ずしも2つ以上を実装するわけではないということです)
- 実装済み:
- html
- image
- video
- plaintext
- 'file' (fallback 代替システム)
- 恐らく将来的に実装されます。
- encrypted pdf
- ims?
- leap/piop? (http://wiki.cetis.ac.uk/LEAP_2.0)
- moodleネイティブ?
- maharaネイティブ?
- Dublin Core (Enovation implemented this)
テスティング
現在のところ、portfoliolib、ボタンオブジェクトおよび呼び出し側は、sha1 (Secure Hash Algorithm 1) の生成が適切に一致しているかどうか確認するため、テストするようにしています。これは、 (コードバック引数を確認する) 呼び出し側オブジェクトの構築に関する、潜在テストも含みます。
現在のところ、リモートシステムとの通信をテストできないため、プラグインはテストされていません。
MNET
このセクションは、開発:MNETロードマップに移動しました。
xmlrpc関数に関するドキュメントは、開発:MNET_APIをご覧ください。
データの複製
どのようなコンテンツが、いつ転送されるのか、Moodleは経過を追います。ユーザが同じコンテンツのエクスポートを試みる場合、Moodleがユーザに警告できるよう、sha1 (Secure Hash Algorithm 1) がデータを持ちます。
しかし、外部システムがどのように処理するかするか関与することはできません。異なるプラグインは、それぞれ自由に動作することができます。例えば、 Maharaはオーバーライトするより、新しいファイルを作成します。box.netプラグインでは、コリジョン (collision 衝突) を避けるため、リネームを試みます。
Moodleのセーブポイント
開発中、http://tracker.moodle.org/browse/MDL-15758 に移動しました。
まだ、やる必要のあること (Still TODO)
様々な理由で私が完了できていないことが、わずかばかりあります (ほとんどの場合、システムの他の部分に依存します。例 Files API)。これらはすべてバグですが、完全性のため、ここに再現します:
- MDL-16406 - QA待ち (Jerome)
- MDL-16048 - QA待ち (Nico)
- MDL-16313 - これは、私のリストから遠くはないのですが、まだどのように関連しているのか確信が持てません。
- MDL-15777 - ファイルAPIに依存 - data_field_fileサブクラスがcopy_existing_fileを使用してエクスポートエリアに対して、データフィールドを別々に解凍およびコピーする必要があります - これは基本的に実行されますが、まだ私は画像をサブクラスファイルにした方が良いと思っています。詳細は、MDL-16493をご覧ください。
- MDL-15777 - ファイルAPIに依存 - プレインエクスポートがods/xlsをサポートしていますが、これら2つのライブラリが新しいファイルAPIに更新されないため、データモジュールはCSVのみエクスポートすることができます。詳細は、MDL-15911をご覧ください。
- MDL-16326 - ファイルAPIに依存 - 「ファイル」リソースモジュールはファイルAPIを使用するよう更新されていないため、このタイプからのエクスポートは、まだ実装されていません (現在、HTMLおよびプレインテキストのみ)。
- MDL-16175 - (現在のところ) 不当に例外 (exceptions) に依存しています。特にキューに入れられたイベント。現在cronでポートフォリオの転送が起動された場合、mnetにおいて (例 リモートサイトがダウンしているか、設定が正しくない) エラーが発生します。このエラーに関して、die()をコールするprint_errorをmnet関数がコールするため、cronジョブ全体が停止してしまいます。これは、転送が終了するまで (Moodleすべてに関して) 基本的にcronが壊れたままになることを意味します。本来これは、ポートフォリオコードのバグではありませんが、すでに不安定な状況を間違いなく悪化させることになります。
単体テスト TODO
現在、多くのテストが実装されていますが、極めて優れている点は、呼び出し側に対してファイルを作成する生成元にテストが依存している点です。テストが失敗し始めた時点 (現在はパスします) で生成元を更新する必要性が明らかになるよう、ポートフォリオ単体テストはportfolio_exporter_text->copy_existing_fileメソッド内で例外 (exceptions) を投げ始めます。
エクスポートシナリオに関する現在の完全なリスト
mod/assignment
単一ファイルのアップロード
これは非常に分かりやすいと思います。単一ファイルの横に (大きなフォームアイコンではなく) エクスポートアイコンを表示します。また、エクスポートは、MIMEベースのサブシステム (_IMAGE、_VIDEO等) を考慮すべきです。
複数ファイルのアップロード
これは、さらに少しだけ複雑です。個々のファイルの横にエクスポートアイコンを表示します。さらに、1つ以上のファイルがある場合、ページ下部に (すべてのファイルをエクスポートする) エクスポートフォームを設置します。複数ファイルをエクスポートする場合、常にMIME検出を停止して、_FILE formatにフォールバック (代替機能への切り替え) します。
単一ファイルの横に (大きなフォームアイコンではなく) エクスポートアイコンを表示します。
オンラインテキスト
ページ下部に完全なフォームを表示します。_HTMLの形式でエクスポートします。
mod/chat
すべて_HTMLの形式でエクスポートして、Moodleへの参照 (例 必ずしも表示する必要のない、ユーザプロファイルのイメージ) は含みません。
セッションページ
セッション全てをエクスポートします。
セッションごとのレポートページ
セッション全てをエクスポートします。
すべてのセッションのレポートページ
すべてのセッションを結合します。
mod/data
単一エントリのエクスポート
HTMLとしてエクスポートします。どのようなファイルでもHTMLに含むことができます。エントリのフィールドが1つのみで、ファイルまたはイメージの場合、MIMEタイプが配慮されるべきです。また、エクスフォーマットは、MIMEタイプ (例 _IMAGE) を基にすべきです。
データベースインスタンス全体のエクスポート
CSVとしてエクスポートします。ファイルは含まれません (他のCSVエクスポートと同じです)。
mod/forum
ディスカッション全体
エクスポートフォーマットは、FILEです。添付ファイルは、discussion.htmlと共にエクスポートされます - 添付ファイルがない場合、後でHTMLに変更することができます。
単一の投稿
エクスポートフォーマットは、_HTMLです。
添付ファイル付きの単一の投稿
エクスポートフォーマットは、FILEです。添付ファイルは、post.htmlと共にエクスポートされます
単一の添付ファイル
MIMEタイプを配慮した形のフォーマット (例 _IMAGE) でエクスポートされます。
mod/glossary
単一エントリのエクスポート
エントリは、HTMLとしてエクスポートされます。
用語集全体のエクスポート
用語集をCSVとしてエクスポートします - 現在の用語集エクスポートに似ています。
mod/resource
HTMLリソース
HTMLとしてエクスポートされます。
テキストリソース
_TEXTとしてエクスポートされます。
ファイルリソース
まだ、実装されていません。ファイルAPIからブロックされています。ファイルのMIMEタイプを配慮して、適切なフォーマットでエクスポートします。
関連情報
- 開発:リポジトリAPI
- 開発:ファイルAPI
- MDL-14591 - ポートフォリオAPI関連項目一覧
