開発:リポジトリAPI
Moodle 2.0
作成中です - Mitsuhiro Yoshida 2008年11月29日 (土) 09:44 (CST)
このページでは、将来の機能に関する仕様を記述しています。現在、Moodle 2.0に取り掛かっています。また、この仕様に関するページは作成中です。
実装状況を確認するには、MDL-13766 をご覧ください。
このページは、誰でも間違いを正したり、内容を改善できるよう、このドキュメントはオープンにされています。しかし、質問、報告する問題、大規模な機能改変に関する提案等は、ページコメントに投稿するか、Repositories forumで新しいディスカッションを開始してください。開発を開始する前、私たちは、そのようなすべての提案をメインの仕様にマージするよう努力します。
このドキュメントの一部分は、開発:ファイルAPIに分離されましたので留意してください。
目的
- すべてのMoodleユーザに対して、Moodle内部のコンテンツを外部のリポジトリに簡単に持ち出せるようにします。
- どのようなMoodleモジュールに対しても、一貫性のある外部レポジトリのインターフェースを提供します。
ユーザ事例
新しいリソースとして、教師が外部ファイルを追加する
- 教師は、コースに新しいリソースを追加したいと考えています。
- 教師が「リソースを選択する」ボタンをクリックします。
- ファイルを選択するため、教師には (複数のリポジトリ間をスイッチできる) 簡単なファイルピッカーが提供されます。
- 教師が、外部リポジトリのファイルを選択します。
- ファイルがMoodle内にコピーされ、リソースモジュールに保存されます。
- ファイルがユーザに所有されている旨、マークされます。
- ユーザがファイルを閲覧したい場合、リソースモジュールがアクセスをコントロールします (詳細は、開発:ファイルAPIをご覧ください)。
新しいリソースとして、教師が外部ファイルのリンクを追加する (ビデオリポジトリを考えます)
- 教師は、ファイルをリポジトリ内に表示したいと考えています。
- 教師が「リソースを選択する」ボタンをクリックします。
- ファイルを選択するため、教師には (複数のリポジトリ間をスイッチできる) 簡単なファイルピッカーが提供されます。
- 教師が、外部リポジトリのファイルを選択します。
- ファイルがMoodle内にコピーされ、リソースモジュールに保存されます。
- ファイルがユーザに所有されている旨、マークされます。
- ユーザがファイルを閲覧したい場合、リソースモジュールがアクセスをコントロールします (詳細は、開発:ファイルAPIをご覧ください)。
学生が課題を提出する
- 学生は課題を提出する必要があり、「ファイルを選択する」ボタンをクリックします。
- 設定されたすべてのリポジトリにあるファイルを閲覧するため、学生は「ファイルピッカー」を確認します (ファイルピッカーログイン、ファイルピッカーブラウザ、ファイルピッカー検索)。
- 学生がリストからMySpaceを選択します。
- 学生がMySpaceのユーザ名/パスワードをの入力を求められます (管理者が許可した場合、「ログイン情報を保存する」チェックボックスを設置することもできますが、セキュリティに関することも考える必要があります)。
- 学生は、MySpaceで自分のファイルを閲覧して、1つまたはそれ以上のファイルを選択することができます。
- ファイルがMySpaceからMoodleにコピーされます。
- 学生および課題評定者のみファイルを閲覧できるよう、課題モジュールがパーミッションをコントロールします (他の学生には、パーミッションが割り当てられません)。
学生がイメージをフォーラムに添付する
- 学生はイメージを添付する必要があります。投稿画面の「ファイルを選択する」ボタンをクリックして、イメージを添付します。
- 設定されたすべてのリポジトリにあるファイルを閲覧するため、学生は「ファイルピッカー」を確認します。
- 学生がリストからMaharaを選択します。
- 学生がMaharaのユーザ名/パスワードをの入力を求められます。
- Mahara内のファイルを学生が確認して、1つのイメージを選択します。
- イメージがMoodleにコピーされます。
- フォーラムモジュールにより、イメージファイルがフォーラム投稿に (参照する形で) 添付されます。
- フォーラムを閲覧できるユーザすべてがファイルを閲覧できるよう、フォーラムモジュールがパーミッションをコントロールします。
学生が同じイメージを他のフォーラムに添付する
- 学生は課題を提出する必要があり、「ファイルを選択する」ボタンをクリックします。
- 設定されたすべてのリポジトリにあるファイルを閲覧するため、学生は「ファイルピッカー」を確認します。
- 学生はリストから「ローカルファイル」を選択して、以前アップロードしたファイルを閲覧します。
- フォーラムモジュールにより、イメージファイルのコピーがフォーラム投稿に添付されます。
- このファイルに対するアクセスをフォーラムモジュールがコントロールします。
上記と同じフォーマットで事例を追加してください。
試作品のスクリーンショット (Mock screenshots)
あなたが最初にファイルピッカーを呼び出し、リポジトリを選択する場合、ログインを求められます (保存されているパスワードが異なる場合も):
https://docs.moodle.org/en/Image:Filepicker_login.jpg
ファイルの閲覧は、以下のようになります:
https://docs.moodle.org/en/Image:Filepicker_browser.jpg
また、検索することもできます:
https://docs.moodle.org/en/Image:Filepicker_search.jpg
全体構造 (General architecture)
それぞれのリポジトリプラグイン (スタンダードMoodleプラグインは、/repository/xxx配下に保存されます) は、スタンダードAPIをサブクラスにして、そのリポジトリ固有のメソッドをオーバーライドします。
例によって、Moodleでは標準設定のように、リポジトリプラグインを有効/無効にする管理設定があります。同様に、ユーザが自分のパーソナルリポジトリをスタンダードリスト (例 Yahooブリーフケース または Google Docs) に追加して、自分のデフォルトリポジトリとして選択できるよう、ユーザ設定があります。
リポジトリが使用される場合、通常ファイルは、その場ですぐにMoodle内へコピーされます。しかし、オプションもあります:
- ファイルを外部に保持したい場合、URIのみ返します (しかし、これにはセキュリティおよび安全性のリスクが存在します)、または
- ローカルファイルコピーを定期的に自動的にリフレッシュします。
- 必要に応じてファイルを手動でリフレッシュします。
Moodle内では、他のファイルと同じく、開発:ファイルAPIからアクセスコントロールされます。
リポジトリシステム要件
Moodleの観点から、それぞれのリポジトリは、ノードの階層だと言えます。
リポジトリは (MUST):
- それぞれのノード (例 ファイル) をダウンロードできるURIであるべきです。
- 特定のノード (例 ディレクトリ) 配下のノード (例 ファイルおよびディレクトリ) のリストであるべきです。これにより、Moodleは (標準的なOSのファイルピッカーに酷似した) 標準的なブラウズインターフェースを構築できます。しかしながら、いくつかのリポジトリでは、完全にrepository_browse()メソッドをオーバーライドして、独自のインターフェースを実装することができます。最終的にファイルのURIになる限り、これはOKです。
リポジトリは、任意に (OPTIONALLY):
- 認証の信任状を必要とします。
- それぞれのノードに関して、さらにメタデータを提供します (MIMEタイプ、サイズ、日付、関連ファイル、ダブリンコア (dublin core) 等)。
- (Moodleが検索フォームを構築できるよう) 検索機能を記述します。
- 著作権および利用規約 (または、ルールに関する情報のみ) を提供します。
リポジトリプラグイン
初期バージョンで私が開発済みにしたいプラグインは:
- local - ユーザベースになる以外、現在のコースベースのファイルマネージャに非常に似ています。
- moodle - セキュアmnetコネクションを通じてアクセスする、別のMoodleサイトへのインターフェースです。
- jsr170 - jsr170をサポートしているシステムと会話することのできるインターフェースです (例 Alfresco)。
- oki - OKIインターフェースでのアクセスを許可する、FedoraのようなOKIエミュレータです。
- briefcase - Yahooブリーフケースへのインターフェースです。
- myspace - MySpaceファイルへのインターフェースです (恐らく、このMySpace APIを使用して)。
- googledocs - Google Docsへのインターフェースです。
- s3 - Amazon S3へのインターフェースです。
- skydrive - Microsoft SkyDriveファイルへのインターフェースです。
- box - box.netへのインターフェースです。
- facebook - Facebookファイルへのインターフェースです。
- merlot - Merlot.org内の学習教材へのインターフェースです。
- flickr - flickrへのインターフェースです。
- youtube - YouTubeへのインターフェースです。
- mahara - インストール済みMaharaへのインターフェースです。
- Dspace - MITからのリポジトリです。
- DOOR - 人気のあるもうひとつのオープンソースリポジトリです。
- SMB共有 - Windows共有のためのインターフェースです。例) ネットワークドライブのパーソナルフォルダ。リンクする必要のあるLDAPのユーザ名では、多くの場合、全体的に/部分的にフォルダ名と同じです。これはSAMBAを使用することで実現できますが、Windowsマシン自体で動作する必要もあります。Linuxの実装に関しては、このブロックをご覧ください。
- WebDAV - 任意に外部WebDAVサーバにアクセスします。
テーブル
リポジトリ
フィールド | タイプ | デフォルト | 情報 |
id | int(10) | オートインクリメント | |
type | varchar(255) | リポジトリのタイプ | |
visible | tinyint(1) | ||
sortorder | int(10) |
リポジトリインスタンス
このテーブルには、すべての外部リポジトリインスタンス設定に関する1つのエントリが入ります。
フィールド | タイプ | デフォルト | 情報 |
id | int(10) | オートインクリメント | |
name | varchar 255 | このリポジトリの名称 (非ユニーク) | |
typeid | int(10) | リポジトリタイプのID | |
userid | int(10) | このリポジトリインスタンスを作成したユーザ | |
contextid | int(10) | このリポジトリが利用できるコンテクスト ( = サイト全体のシステムコンテクスト) | |
username | varchar(255) | ログインに使用するユーザ名、必要であれば (殆ど使いません!) | |
password | varchar(255) | ログインに使用するパスワード、必要であれば (殆ど使いません!) | |
timecreated | int(10) | このリポジトリが作成された日時 | |
timemodified | int(10) | 最後にリポジトリが修正された日時 |
repository_instance_config
フィールド | タイプ | デフォルト | 情報 |
id | int(10) | オートインクリメント | |
instanceid | int(int) | ||
name | varchar(255) | ||
value | Text |
ファイルタイプ
ユーザがファイルを登録するコンテクストでは、特定のファイルタイプを含む必要があります (例 ユーザの新しいプロファイルイメージをアップロードする場合、イメージのみを考えます)。
これをサポートするには、呼び出されるコードは、必須のMIMEタイプを指定できるようにする必要があります。また、一覧表示するコードは、MIMEタイプを基に、表示結果をフィルタできるようにすべきです。理想的には、リポジトリ自身が高速でフィルタリングできた方が良いでしょう (しかし、すべてのリポジトリがこれをサポートできるわけではありません)。
私たちは、バックアップ (application/vnd.moodle.backup) のようなMoodleの新しいMIMEタイプおよびIMS学習デザイン (IMS learning design) のMIMEタイプ (application/vnd.moodle.imsld) 等を開発する必要があります。
テクニカルウォークスルー
(機能仕様の詳細は、開発:リポジトリファイルピッカーもご覧ください。)
リポジトリAPIの使用には、2つの主要なケースがあります: ファイルを追加するためのMoodleフォームの一部として、およびHTMLにメディア要素を追加するためのHTMLエディタの一部として)。また、私たちはJavaスクリプトを使用しないModoleフォームも提供します。
ファイルピッカーのダイアログを使用して、現在のアクティブなユーザの一時ファイルエリアに保存されますが、これらすべてのケースでは、ファイルはMoodleにアップロードされます。フルコンテクストおよびファイルを適切に保存するためのアイテムIDを知ることができるのは、Moodleフォーム全体が送信された後です。この時点で、ファイルが正しいファイルエリアにコピーされます。
ケース1: Moodleフォームの一部として (Javaスクリプト使用)
1. ファイルが必要とされる場合、常にMoodleのモジュールコードは、ファイルAPIに渡す以下の情報を含めて、ファイルピッカー (filepicker) Moodleフォームアイテムをコールします:
例 $mform->addElement('filepicker', 'uniqueelementid', $fullname, $data)
2. フォームを作成する場合、Moodleはリードオンリーのファイル名フィールドおよび「ファイルを探す」ボタンを表示します。後でファイルリファレンスを保存するため、非表示フィールドも作成されます (実際には、このフィールドが使用されます。ファイル名フィールドは、ユーザがファイルの名称を確認するためだけに使用されます)。
3. ファイル追加ボタンがクリックされた場合、フォームは、AJAXファイルピッカーを含む大きなリサイズ可能なページと入れ替えられます (ファイルを選択した後、画面は閉じられます)。 (必要に応じて、このページをポップアップウィンドウにするユーザオプションがあります)
4. AJAXファイルピッカーインターフェースは、すべてのアクティブなリポジトリをメニューとして一覧表示します。また、ファイルをいくつかのフォーマット (Windows/Mac/Linux等) のひとつを使って、詳細、ファイル名、アイコンとして一覧表示します。
5. それぞれのプラグインにおいて、最初に (必要であれば) AJAXインターフェースがユーザへのログインを促します。また、背後ではプラグインにログインを求めます。クリックおよび検索に応じて、リスティングデータを戻すこともプラグインに求めます。
6. 最後に、ユーザがファイルを選択して「選択」ボタンをクリックした場合、ファイル保存API (ファイルを取得して、「uniqueelementid」および現在のユーザ情報を使用することでファイルを保存) をコールするプラグイン内のメソッドをAJAXインターフェースが始動 (trigger) させます。この間、インターフェースは、 (理想的には) ある種のプログレスバーまたは少なくとも「ファイルのローディング中」イメージ/サイン/メッセージを表示します。
7. 最終的にファイルが選択された後、私たちはオリジナルのMoodleフォーム (uniqueelementid_formidという隠しフィールド) に渡すことのできるファイルIDを取得します。ピッカーは、リードオンリーのファイル名フィールドが非表示になる前にリネームすることができます。
8. フォームを送信することで、フィールドのチェック、モジュール内でのデータ作成等、mform処理が始動されます。この処理が成功した場合、それぞれのファイル情報を「修正」して、ファイルをモジュールのファイルエリアに移動するため、開発者は最後にmform関数をコールする必要があります:
例 $mform->store_local_file('uniqueelementid', $context, $filearename, $itemid, $filepath);
9. ファイル保存APIのCronジョブは、ユーザ一時ファイルエリアにある7日以前のファイルすべてを自動的に削除するか、ユーザファイルエリアのゴミ箱に移動します (恐らく)。
ケース2: Moodleフォームの一部として (Javaスクリプト未使用)
ステップ 1-2は、Javaスクリプトのケースと同じです。
3. ファイル追加のボタンは、異なる値をフォームに送信するための送信ボタンです。ファイル追加ボタンがクリックされた場合、
- フォーム全体が (異なる送信ボタンの値で) オリジナルロケーションに送信されます。
- moodleforms get_data() は、これが「リポジトリの保存」だと判断して、戻すURIと共にopenfile要素のidでタグ付けされたセッションに、すべてのPOST情報を保存します。
- それから、moodleforms get_data() は、メインのピッカーインターフェースを表示する新しいページにユーザをリダイレクトします。
4. ファイルピッカーのインターフェースは、完全に新しいもので、AJAXインターフェースから分離されるべきです。恐らく、長い階層構造のリストになるか、数多くリロードされるものとなります。
5. 最後にユーザがファイルを選択した後、「選択」ボタンを選択してファイルをpicker.phpに送信した場合、ファイルを取得して、すでに私たちが持っているファイルエリアおよびコンテクストの情報を使用してファイルを保存するため、ファイルAPIをコールするプラグイン内のメソッドを始動 (trigger) させます。この間、インターフェースは、 (理想的には) ある種のプログレスバーまたは少なくとも「ファイルのローディング中」イメージ/サイン/メッセージを表示します。
6. この後で、picker.phpはオリジナルのフォームページにリダイレクトします。フォームは、通常どおり作成されます。しかし、フォームがdisplay()メソッドを使用して表示される場合、moodleformsはセッションの保存コンテンツを探して、フォーム内のすべてのコンテンツをオーバーライドします (そして、セッションに保存された情報を削除します)。
ステップ 8-9は、Javaスクリプトのケースと同じです。
ケース3: HTMLエディタの一部として
ここでキーとなるのは、私たちのHTMLテキストへの絶対URIの保存を避けることです。代わりに、私たちは相対名を保存します。
1. テキストエリア (HTMLエディタ) のmoodleformでは、このHTMLに関するfileareaのパスを必要とします 例) wwwroot/pluginfile.php/13/content/0/。まだ、fileareaがない場合、これはuser_draftエリアである必要があります 例) wwwroot/draftfile.php/userid/tempfile/uniquelementid
2. すべてのテキストエリアでは、エディタ内で正常にイメージが表示されるよう、 str_replaceを使用して、コンテンツ内のイメージを@@pluginfile@@/somefilenames.jpgのようなパスを使用する形に置換する必要があります (また、このテキストを表示する場合、すべてにおいてformat_textコマンドも実行する必要があることに留意してください)。
3. 同様に、パスパラメータは、現在のページのエディタ設定に追加される必要があります。
4. これらの変数を探すため、エディタプラグインをエディタ設定で変更することができます。
5. イメージまたは他のメディア要素を追加する場合、すべてのリポジトリよりファイルを選択してダウンロードできるよう、同じAJAXリポジトリピッカーでポップアップウィンドウを表示します。リポジトリピッカーは、ファイルをリアルタイムでダウンロードすること、ファイルエリアが存在しない場合、ユーザ一時ファイルエリアにファイルを保存すること、提供されたパスをファイル名の先頭に付けること、閉じる前にテキスト入力ダイアログにURIを戻すことに関与します。
6. 送信時、およびHTMlが閉じられた後、私たちは永続的な新しいファイルエリアを持つことになります。そのため、私たちは、適切なファイルエリア情報を持つよう、すべての関連する一時ファイルを更新する必要があります。
リポジトリプラグイン
それぞれのリポジトリプラグインは、以下の要素を含む必要があります:
class repository()
このクラスでは、ファイルの閲覧、選択および更新に関して、リポジトリのインターフェースを実装します。The base class (repository) is defined in /repository/lib.php, while each repository defines an inherited class (eg repository_alfresco) in /repository/repositoryname/repository.class.php
Repositories can redefine any of these methods as required (and in some instances, MUST redefine them):
__construct($repositoryid, $contextid, $options=array())
MUST redefine
Accept necessary parameters, and do initialization of repository.
get_file($url)
Given a URL, download a file from there, save the file in a temporary directory.
get_listing($parent='/', $search=''')
Given a path, and perhaps a search, get a listing of files. In the case of AJAX file picker, this function should return json format Javascript array.
print_login()
MUST redefine
Show the login screen, if required. In the case of AJAX file picker, this function should return json format array which defined the login form.
print_listing
Get a listing from get_listing, print it or return HTML code.
print_search
MUST redefine
Print the search form
@TODO: Think about are we really need it?
store_login($username, $password, $userid=''')
If you do want to cache login details for various repositories, then use this method.
cron()
Defines operations that happen occasionally on cron.
ajax_info()
Return information for creating ajax request
create()
Create an instance
delete()
Delete this instance from `repository` table
hide()
Hide a repository instance from file picker list
set_option()
set options in data1-data5 fields, can be overrided
get_option()
get option list or a specific option from database
has_admin_config
If this plugin need admin settings, please refine this function to return true
admin_config_form
if has_admin_config return true, this function MUST redefine, it will help to build the setting form.
get_option_names
if has_admin_config return true, this function MUST redefine, it will return option names
more to come
icon.png
A logo that represents the repository. Ideally square but we should handle all sizes.