Genericoフィルタ

Genericoの使い方（Video Easyについても）

はじめに

GenericoとVideo Easyは、技術的にはMoodle用のフィルタです。しかし、それだけではどのように役立つかを説明することはできません。 ユーザの言葉で言うと、これらは管理者がMoodleのHTMLエリアに入れることのできる、html/cssおよびjavascriptの再利用可能なスニペットを定義することができます。これらのスニペットはテンプレートと呼ばれます。シンプルなテンプレートは、現在ログインしているユーザの名前を含むウェルカムメッセージ、メインコースページに戻る魅力的なグリーンボタン、ビデオプレイヤ、またはFAQスタイルのアコーディオンを表示するために使用することができます。より高度なテンプレートは、QRコード、音声合成ウィジェット、画像スライドショーなどに使われています。

これの何が良いのでしょうか？複数のプラグインやカスタムPHPコーディングに頼ることなく、あなたのMoodleサイトをカスタマイズすることができます。 また、免責事項や著作権表示のような一般的なHTMLを一元化して再利用することができます。最後に、一般的にiframeを埋め込む許可を与えることなく、あなたのユーザが特定のサイトからiframeコンテンツを埋め込むようなタスクを実行できる方法を提供します。

テンプレートの作成には、テンプレートの複雑さと同じくらいのスキルが必要です。しかし、すでに作られているテンプレートを使用するには、特別なスキルは必要ありません。GenericoにもVideoEasyにも、あらかじめ作られたテンプレート集が用意されているので、すぐに使い始めることができます。

GenericoとVideoEasyの違いは何ですか？

これらは非常に似ており、テンプレートメーカの観点からはほとんど同じものです。主な違いは、Moodleがどのようにして、いつHTMLページにテンプレートを適用するか、そしてどのように変数をテンプレートに渡すかです。

VideoEasy

VideoEasyは、ページ上のhtmlリンクを探して動作します。HTMLリンクがVideoEasyに登録されているファイル拡張子と一致した場合、そのリンクを処理されたテンプレートに置き換えます。

つまり、拡張子が.mp4のビデオファイルへのリンクは、mp4ビデオプレイヤに置き換えられるのです。VideoEasyの名前にもかかわらず、VideoEasyはビデオに限定されません。他のファイル拡張子も登録できます。例えば、.pdfの拡張子を登録して、.pdfのリンクをpdfビューアに置き換えることができます。

VideoEasyが扱うべきファイルの拡張子は、以下の場所に登録されています。 サイト管理 -> プラグイン -> フィルタ -> Video Easy -> 一般設定

ファイルの拡張子に使用される実際のテンプレートは、同じページに登録されます。この設定は、活動インスタンスの設定メニューからアクセスした "フィルタ" ページの "設定" ボタンを介して、コースまたは活動レベルで上書きすることができます。これにより、コースや活動ごとに、必要に応じて異なるビデオプレイヤを使用することができます。

HTMLリンクのURLにパラメータを追加することで、テンプレートに変数を渡すことができます。http://mysite.com?favoritefruit=apple のURLでは、変数 'favoritefruit' に 'apple' という値が設定され、@@favoritefruit@@としてテンプレートに渡されます。

Generico

Genericoは、VideoEasyとは少し異なる仕組みを持っています。テキストエリア内のリンクに作用するのではなく、以下のような特別にフォーマットされたテキストブロックに作用します: {GENERICO:type="greenbutton",text="Go Back"}

これらを見つけると、処理されたテンプレートに置き換えられます。テンプレート作成者は、これらの巧妙な小さなテキストブロックを手作業で作ることができるかもしれませんが、一般ユーザにとっては現実的ではありません。そこで、Genericoのフィルタ文字列をユーザに代わって作成することができる、Attoテキストエディタ用の特別なプラグインが用意されています。

Genericoテンプレートの使用

Genericoのテンプレートをページに追加する方法は2つあります。

i) ページにGenericoのフィルタ文字列を手動で入力する
ii) AttoテキストエディタのGenericoポップアップダイアログからGenericoテンプレートを選択する。

ほとんどの場合、シンプルでヒューマンエラーが起こりにくい後者を使用します。カスタムキャプションとリンク付きの可愛いボタンを表示するGenericoテンプレートの例を見てみましょう。このような場合、Genericoフィルタを手動で追加すると次のようになります: {GENERICO:type=prettybutton,caption="Generico goes to Google",link="http://www.google.com"}

しかし、Attoのポップアップダイアログを使用した場合は、まず以下のようになります:

しかし、Atto Genericoプラグインを使ってGenericoの文字列をページに挿入しても、それはただのGenericoの文字列です。ボタンのようには見えません。これは、Genericoがフィルタ文字列を処理するのが、html領域のコンテンツが保存され、それを含むページが表示されてからだからです。

Genericoのテンプレート...を "テンプレート" と呼んでいるのは、いくつかのデータと組み合わせて、ページに表示される最終的なhtmlスニペットを作成するからです。可愛いボタンの場合、このデータはキャプションとURLでした。テンプレートを作成する際には、変数と呼ばれるプレースホルダーが挿入されます。そして、そのテンプレートをページに追加する際に、キャプションやURLなどのデータを渡すと、それらがテンプレートにマージされてhtmlスニペットが作成されます。テキストエディタGenerico Attoでは、変数ごとにフィールド（テキストエリアやドロップダウンリストなど）を持つシンプルなフォームを生成し、ユーザが簡単に操作できるようにしています。

シンプルなGenericoテンプレートの検討

それでは、シンプルなGenericoのテンプレートを作ってみましょう。テンプレートはサイト管理エリアで定義されます。それぞれのテンプレートには、以下のようなエントリがあります: サイト管理 -> プラグイン -> フィルター -> Generico

Genericoをインストールすると、デフォルトで20個の空のテンプレートが用意されていますが、さらに追加することも可能です。Genericoの空白のテンプレートは何もしないので、何かをする前に記入する必要があります。しかし、あらかじめ用意されているテンプレートを利用すれば、何かをするための新しいテンプレートを作るのは簡単です。一番シンプルな "hello world" というテンプレートを使ってみましょう。これを行うには i) 空のテンプレートを開きます。 ii) テンプレート設定ページの最初のコントロールで、テンプレートのプリセットのドロップダウンリストから "hello world" を選択します。 iii) 一番下までスクロールして、テンプレートを保存します。 以上でテンプレートの作成は完了です。フィルタ文字列 "{GENERICO:type=helloworld}" をHTMLエリア（フォーラムの投稿やページのリソースなど）に入力するか、Generico attoエディタプラグインからフィルタ文字列を選択して挿入します。ページが表示されると、"hello world [yourname]." というメッセージが表示されるはずです。

では、実際に何が起こったのか？それは次のようなものです....

a) Moodleはブラウザにページを送信します。
b) Genericoのフィルタ文字列を探すためにページを検索し、見つかると:
 i) 出力からフィルタ文字列を削除します。
 ii) フィルタ文字列を処理して、処理済みの出力に置き換えます。
c) その出力をページに送ります。

この処理では、テンプレート内の可変プレースホルダーを探し、フィルタ文字列のデータと照合します。一致すると、テンプレート内の可変プレースホルダーがフィルタ文字列のデータと交換されます。そして、処理されたテンプレートがブラウザに返されます。この動作については、後で詳しく説明します。

テンプレートのインポートとエクスポート

自分や他の人が作成したテンプレートを共有するために、テンプレートをインポートおよびエクスポートすることが可能になっています。テンプレートの設定ページの右上には、"Bundle" という緑色のボックスがあります。このボックスをクリックすると、テンプレートがテンプレートキーと同じ名前のテキストファイルにエクスポートされます。"helloworld" というテンプレートの場合、hello world.txtというファイルがエクスポートされ、すぐにダウンロードが開始されます。このようなファイルをインポートするには、テキストファイルを緑色のバンドルボックスにドラッグします。すると、枠が青くなります。ファイルをドラッグ＆ドロップすると、現在読み込まれているテンプレートが、インポートされた内容で上書きされたり、埋められたりします。ただし、この変更はテンプレートが保存されるまで永続的ではありません。そのため、ページの一番下までスクロールして、保存ボタンを押す必要があります。

テンプレートのフィールド

各テンプレートの設定ページでは、「Video Easy」にはX個、「Generico」には14個のフィールドが用意されています。順番や名前の付け方も少し違います。それぞれのフィールドは、4つのカテゴリのうちの1つだと考えることができます。一般、HTML、Javascript、CSSです。hello worldテンプレートの場合、javascriptもCSSもありません。HTMLを返しているだけです。しかし、必要に応じてCSSスタイルを追加したり、javascriptのクリックイベントをテキストに追加したりすることができます。各フィールドを順に見ていきましょう。

a) The Template Key
b) The Template Name
c) The Template Instructions 
d) The Template Body
e) The Template Body End
f) The Template AMD flag
g) The Template JQuery flag
h) The Template Require JS 
i) The Template Script 
j) The Template Upload JS
k) The Template Require CSS
l) The Template CSS
m) The Template Upload CSS
n) The Template Dataset
o) The Template Dataset Datavars

The Template Key

The Template Keyは、内部処理で使用される一意の識別子であり、Genericoのフィルタ文字列の中で最も重要な部分です。Keyにはスペースや英数字以外の文字（アンダースコアは可）を含めてはいけません。例えば、先ほどの prettybutton の例では、The Template Keyは "pretty button" となります。 {GENERICO:type=prettybutton,caption="Go to Google",link="http://google.com"}

テンプレートの他の部分はすべて変更することができ、テンプレートが処理されるとそれに応じて動作も変わります。しかし、Keyを変更すると、そのテンプレートのためにサイト上に存在するすべてのフィルター文字列は処理されなくなります。これは、"タイプ" がどのテンプレートのKeyとも一致しないためです。

The Template Name

The Template Nameは、サイト内でテンプレートを参照する際に表示される名前です。例: 設定ページやAttoのテキストエディタで表示されます。"Key" とは異なり、スペースや英数字以外の文字を含めることができます。

The Template Instructions

The Template Instructionsは、AttoテキストエディタGenericoのテンプレートの挿入フォームに表示されます。ここにはあまりスペースがありませんので、短い説明が最適です。

The Template Body

The Template Bodyは、処理されているGenericoフィルタの文字列の代わりに、ページ上に配置されるべきhtmlを置く場所です。"helloworld" の例では、The Template Bodyは次のようになります。 Hello World @@USER:firstname@@

変数を使用していることに注意してください。この場合、現在のユーザのファーストネームを返すプリセット変数を使用しています。しかし、ここで重要なのは、一般的なフィルタ文字列の実際の置き換えはここで行われるということです。Bodyセクションの内容が文字列を置き換えますが、変数は実際の値に置き換えられます。

The Template Ends Section

これはGenericoにのみ存在します。これは、フィルタ文字列のtype属性が 'type=[key]_end' というフォーマットの場合、"The Template Body" セクションの代わりに処理されます。これは、テンプレートに開始タグと終了タグが必要な場合に使用するためのものです。例えば、ボタンが押されたときに画像をlightboxに表示するlightboxのテンプレートを考えてみましょう。2つのgenericoフィルタ文字列をページに配置し、1つは開始タグ用、もう1つは終了タグ用とします。つまり、次のようになります: {GENERICO:type=lightbox} {GENERICO:type=lightbox_end}

ユーザはエディタ上の標準的なMoodleの "画像を挿入する" アイコンを使って、それらの間に画像を挿入することができます。 Generico AttoプラグインはテンプレートのEndフィールドを認識し、それが空白でない場合、メインのフィルタ文字列と一緒にEndのフィルタ文字列をページに自動的に挿入します。

The Template AMD flag

AMDは、Moodleのバージョン2.9で導入されたjavascriptのロードシステムです。AMDは、あなたのテンプレートに依存するすべてのjavascriptを安全にロードし、同じページにある他のテンプレートおよびjavascriptの依存関係との名前およびバージョンの衝突を防ぎます。あなたのテンプレートがjavascriptを使用していない場合、またはMoodle 2.9より古い場合は、この問題を心配する必要はありません。あなたが "Template script" エリア (後述) でjavascriptを使用する場合、AMDを "yes" に設定することで、あなたのスクリプトでjQueryが使用できるようになります。"Template require JS" または "Template upload JS" エリアでサードパーティのライブラリを読み込む場合は、サードパーティのライブラリが推奨するものを選択する必要があるかもしれません。AMDをサポートするライブラリは、"yes" を選択しないと一般的に失敗します。AMDをサポートしていないライブラリは、"yes" を選択すると通常は失敗します。

The Template JQuery flag

サードパーティのライブラリや自分のスクリプトがJQueryに依存している場合、これを "yes" に設定することで、強制的にJQueryを読み込むことができます。しかし、これは絶対にすべきではありません。他の方法があれば、それに越したことはありません。(注意: 技術的な説明が続きます）その理由は、jQueryにはバージョンとプラグインがあるからである。他のテンプレートやページ上の何かがjQueryプラグインをロードしていたり、異なるバージョンのjQueryを必要としている場合、jQueryを強制的にロードすると、他の何かが既にロードしていたjQuery（およびプラグイン）を上書きしてしまいます。その場合、他のものは失敗します。このようなコンフリクトは追跡するのが難しく、AMDシステムが回避するために設計されたものです。どうしてもjQueryが必要で、AMDが使えない場合は、jQueryをロードするテーマを使うようにします。Essentialのような優れたテーマのほとんどがそうです。そうでない場合、moodleの追加HTMLエリアの "HEAD" セクションで、jQueryコールを追加してください。(Moodleの追加HTMLセクションを使用してjQueryをロードしても、jQueryを必要とする他のプラグインで問題が発生するリスクがあることに注意してください)。

ここにいる開発者は、GenericoやVideoEasyがPHPの$PAGE requirements managerを使ってjQueryをロードしないことを不思議に思うかもしれません。問題は、ページヘッダがすでにブラウザに送信された後にフィルタが呼び出されることが多いことです。その時点で$PAGE requirements managerを使ってjQueryを要求しようとすると、エラーになってしまいます。

The Template Require JS

lightboxを作成するためのライブラリなど、サードパーティのライブラリを必要とするテンプレートの場合は、ライブラリのURLをここに記載することができます。これは、ライブラリがCDN（コンテンツ・ディストリビューション・ネットワーク）経由で提供されている場合に便利です。ライブラリ自体をテンプレートに含める必要はなく、URLを指定するだけなので、多くのプリセットやGenerico/VideoEasyのバンドルはこの方法でサードパーティのライブラリを読み込んでいます。

ライブラリのURLを指定する際には、https:やhttp:ではなく、//で始まります。

The Template Script

The Template Scriptが指定されている場合は、ページ上のテンプレートのフィルタ文字列ごとに1回ずつ呼び出されます。テンプレートを起動するために必要なイベントハンドラやDOM操作を設定するために、このスクリプトを使用するのが一般的です。例えば、lightboxで画像を開くボタンをページ上に配置する場合、"Template body" にボタン用のhtmlを追加し、クリックイベント用のイベントハンドラをここにアタッチします。この場合、一般的には、ボタンにclassやid属性を与え、そのclassやidに対応する要素をスクリプトエリアで選択する必要があります。これは、スクリプトが実行されるのは、ページ上のすべてのhtmlが読み込まれた後だからです。"Template Script" と "Template Body" の領域で同じidやクラスを簡単に使えるように、特別な変数AUTOIDが用意されています。この変数は、要素のidやclassとして使用できるランダムでうまくいけばユニークな文字列を提供し、特定のフィルタ文字列の処理中に同じものが使用されます。

さて、ここで変数の話をしておきましょう。テンプレートでは、自分で定義した変数を使うこともできますし、プリセットの変数を使うこともできます。AUTOIDとUSER:firstnameはプリセット変数の2つの例です。Generico/VideoEasyは、これらの変数に正しいデータが含まれていることを確認します。自分でカスタム変数を宣言することもできます。二重の@@マークで囲まれたものは変数として扱われます。つまり、テンプレートの@@AUTOID@@と@@FAVORITECOLOR@@は変数として認識されます。カスタム変数の場合、Genericoはフィルタ文字列から値を取得します。VideoEasyは、URLパラメータからカスタム変数の値を取得します。また、Generico/VideoEasyにデフォルト値を設定することも可能で、指定されていない場合はデフォルト値が使用されます。

変数を使用する際には、重要な注意点があります。変数は、"Template body" や "Template script" の領域で使用することができます。しかし、処理が少し違います。Template bodyでは、変数@@FAVORITECOLOR@は 'pink' に置き換えられるかもしれません。しかし、Template scriptでは、'opts['FAVORITECOLOR']' に置き換えられます。

そのため、"Template body" では、変数を好きなように配置することができ、その変数はそのまま値と交換されることになります。しかし、"Template script" では、次のようなことを書かないように注意しなければなりません。 var elem = $('#@@AUTOID@@');

これが失敗するのは、処理後に次のようになるからです: var elem = $('#opts['AUTOID']');

代わりに次のように書きます: var elem = $('#' + @@AUTOID@@);

これで動作して、次のようになります: var elem = $('#' + opts['AUTOID']);

あなたは、なぜスクリプトをこのようにしなければならないのかと思うかもしれません。その理由は、スクリプトファイルがMoodleにキャッシュされるからです。opts変数を変数のリテラル値の代わりに使用することで、キャッシュがうまく機能し、ユーザに古いコンテンツ (または他の人のコンテンツ) を提供することがなくなります。

The Template Upload JS

Upload JSエリアでは、管理者が "Template require js" ファイルがロードされるのと同じ方法でロードされるjavascriptファイルをアップロードすることができます。これは、テンプレートのrequire jsファイルに加えて使用することができ、複数のサードパーティライブラリファイルが必要な場合、またはCDNや他のインターネットソースからではなく、Moodleサーバからjavascriptファイルをロードしたい場合に便利です。

The Template Require CSS

テンプレートがサードパーティのCSSファイルを必要とする場合は、ここにライブラリのURLを置くことができます。ライブラリのURLを指定する際は、先頭に//をつけてください（https:やhttp:ではありません）。

The Template CSS

テンプレートのカスタムCSSをここで指定します。残念ながら、カスタムCSSエリアでテンプレート変数を使用することはできません。カスタムCSSはかなり遅れて読み込まれるため、スタイルの適用が遅れるとユーザに気づかれてしまいます。これが気になる場合は、カスタムCSS宣言をファイルに保存して、"Template upload CSS" エリアにアップロードしてください。

The Template Upload CSS

"Template upload JS" エリアと同様に、"Template upload CSS" エリアでは、テンプレート作成者がサードパーティ製のCSSファイルをアップロードすることができます。この機能は、ローカルサーバからファイルにアクセスする場合や、"カスタムCSS" で指定したスタイルよりも早くCSSスタイルを適用する場合に便利です。

The Template Dataset

また、サーバサイドで実行され、結果のデータがあなたのテンプレートに返されるカスタムSQLスクリプトを設定することもできます。SQLスクリプトは、Moodleの$DB->get_records_sql()関数を使用して、呼び出されます。参照: https://docs.moodle.org/dev/Data_manipulation_API#moodle_database::get_records_sql.28.29

返されたレコードが1つだけの場合、そのレコードは、次の構文@@DATASET:[フィールド名]@@を使って、Template bodyエリアで使用できます。 例 Template dataset: “SELECT * FROM {user} WHERE id = 37;” Template body: User 37’s first name is @@DATASET:firstname@@, don’t forget it.

Datasetを指定した場合、1つのレコードでも多数のレコードでも、@@DATASET@@変数がテンプレートのカスタムjavascriptで使用可能になります。これは、オブジェクトの配列で、各オブジェクトは返されたレコードの一つを表します。PHP のオブジェクトの配列から javascript のオブジェクトの配列に変換する過程で、 配列内のオブジェクトの順序やインデックスが変更されているように見えるため、 これを信頼することはできません。

The Template Dataset Variables

テンプレート変数は、Template datasetでは動作しません。これは、get_records_sql apiが独自のテンプレートシステムを持っているからです。この関数の最初のパラメータは、SQL文です。SQL文の中にクエスチョンマーク (例: '?') を入れると、Moodleはそれを変数として認識します。変数の値は、関数の2番目のパラメータに渡されます。Moodleは各クエスチョンマークを2番目のパラメータで渡された値の1つと交換します。Genericoはこのシステムを使用し、「Template Dataset Variables」フィールドに変数値のコンマ区切りリストを指定することができます。ここにGenericのテンプレート変数を指定することで、大きな力を発揮することができます。上の例を、現在ログインしているユーザの情報を返すように書き換えて、これを実演してみましょう。

Template dataset: “SELECT * FROM {user} WHERE id = ?;”

Template dataset vars: @@USER:id@@

Template body: User @@USER:id@@’s first name is @@DATASET:firstname@@, don’t forget it.

Genericoの@@USER:xx@@変数を使って、現在ログインしているユーザの情報にすでにアクセスしているので、実際にはこれは些細なことです。しかし、これはGenericoのテンプレート変数を使って、データベースからDatasetを引き出す方法を示しています。@@USER:xx@@、@@COURSE:xx@などのプリセット変数のほか、自分で定義した変数を使うこともできます。

get_records_sqlから返されるレコードが複数ある場合、@@DATASET:xx@にアクセスしてフィールドを取得することはできません。この場合、@@DATASET@にはオブジェクトの配列が格納され、実際に役立つのはカスタムjsの領域だけです。各オブジェクトはDatasetのレコードを表します。配列のインデックスは、おそらく返されるレコードのIDになりますので、@@DATASET@[0]で最初のレコードを取得することはできません。

データを取得するためのajaxコールはありませんのでご注意ください。フィルタが解析されたときにデータが取得され、それ以降は取得されません。

NB Genericoの現在の実装のバグにより、Dataset variablesで指定された変数セットのうち、最初のものだけが実際にプラグインで利用できるようになっています。

ネイティブ変数

GenericoとVideo Easyには、すぐに使える変数がたくさん用意されています。例: @@AUTOID@や@@USER:firstname@など。

共通のネイティブ変数

これは1つしかありません。しかし、良いものなので、よく使うでしょう。

AUTOID = container divやその他の場所で使用する、自動生成されたID

これは、HTML要素に一意のIDを与えるために使用され、javascriptから検索できるようになります。 AUTOIDの値は、フィルタを実行するたびに異なりますが、テンプレートの各フィールドでは同じ値になります。

Genericoネイティブ変数

USER:xxxx =現在のユーザのユーザレコードからの値 xxxx= ユーザレコードのフィールド

COURSE:xxxx 現在のコースレコードからの値 xxxx=コースレコードのフィールド

WWWROOT = MoodleサイトのURL

MOODLEPAGEID = 現在のページのURLに渡されたidパラメータの値(もしあれば)

URLPARAM:xxxx = 現在のページに渡されたURLパラメータの値。xxxx= urlパラメータ。videoeasyでは、URLパラメータは、URLPARAM:ビットなしで、トップレベルのネイティブ変数として使用できます。

Video Easyネイティブ変数

FILENAME = ビデオのファイル名

AUTOJPGFILENAME = ビデオのファイル名だが、拡張子がjpgのもの

AUTOMIME = ファイルの拡張子によって決まるビデオファイルのmimeタイプ

AUTOPNGFILENAME = ビデオのファイル名だが、拡張子がpngのもの

AUTOPOSTERURLJPG = ビデオの完全なURLだが、拡張子はjpgのもの

AUTOPOSTERURLPNG = ビデオの完全なURLだが、拡張子はpngのもの

CSSLINK = 必要に応じてCSSファイルを読み込むために内部的に使用される

DEFAULTPOSTERURL = デフォルトのポスター画像のURL。VideoEasyには灰色の画像が同梱されています。しかし、VideoEasyの一般設定ページで、独自のデフォルトポスター画像をアップロードすることができます。

FILEEXT = ビデオファイルのファイル拡張子

VIDEOURL = ビデオのURL

URLSTUB = ビデオのURLからファイル拡張子を除いたもの

PLAYER = プレイヤの種類 (videojs, flowplayer ...etc)

TITLE = ビデオのタイトル (リンクされたテキストから)

WIDTH = ビデオの幅

HEIGHT = ビデオの高さ