blocktype/creativecommons と artefact/file/blocktype/image を参考にして。

ここにも参考資料が。


必要なファイル

全てを一つのディレクトリにまとめる。ディレクトリの名前=プラグインの名前。プラグインの名前はひとつの Mahara でユニークでなくてはならない。

ディレクトリの置き場は htdocs/blocktype もしくは artefact に関連するものであれば htdocs/arterfact/${ARTEFACTYPE}/blocktype/

ディレクトリの中には最低限以下のファイルが入っていなくてはならない

  • lib.php
    プラグインの本体。ブロックを表示するためのロジックを記述する。
  • thumb.png
    プラグインアイコン。View編集のときにドラッグ&ドロップで配置するために使う。70x58のPNGイメージ。「Mahara1.5以降用のプラグインアイコン」からブランクのテンプレートアイコンイメージが取得できる。後述のように、テンプレートを使う場合はthemeディレクトリ以下に入れていることが多いようだ。
  • version.php
    プラグインのバージョンを示すファイル。通常は、version の値と release の値を与える。versionは日付とバージョンを示す数値を YYYYMMDDNN という形式で与える。NNは00から始まる増加する数。以下のような記述になる。(defined.. はおまじない)
    defined('INTERNAL') || die();
    
    $config = new StdClass;
    $config->version = 2010042800;
    $config->release = '1.0.0';
  • lang/en.utf8/blocktype.${BTNAME}.php
    プラグイン内で使われるすべての文字列を保持する。オプションで英語以外の言語を用意する場合は、en.utf8 と同じレベルに xy.utf8 というディレクトリを用意する。xy は ISO 639-1 で定義される言語コード。

テンプレートやイメージファイルなどを使う場合は以下のディレクトリに諸々纏める。

  • theme/raw/

この場合には、アイコンファイルも以下に与えているようだ。

  • theme/raw/static/images/thumb.png

Dwooテンプレートファイルを使う場合は、raw以下にテンプレートファイルをおく。また上記イメージ用フォルダにあるファイルのURLは、プラグインコード中で下記のようにして取得できる。(CreativeCommons Blocktype Plugin より)

global $THEME
$smarty = smarty_core();
$smarty->assign('licenseurl', $licenseurl);
$smarty->assign('licenselogo', $THEME->get_url('images/' . $licensetype . '-3_0.png', false, 'blocktype/creativecommons'));
$smarty->assign('licensestatement', $licensestatement);
$smarty->assign('otherpermissions', $otherpermissions);
return $smarty->fetch('blocktype:creativecommons:statement.tpl');

言語ファイル

言語ファイル内のデータの取り扱いは、他のMaharaコードと同様。以下のように言語ファイル内での定義は string 配列として与える。

$string['alttext'] = 'Creative Commons license';
$string['cclicensename'] = 'Creative Commons %s 3.0 Unported';

定義した文字列をプラグインコード中で取得するにはget_string関数を使う。

get_string('alttext', 'blocktype.${BTNAME});

文字列にフォーマット指定子が含まれているばあい、get_string の三つ目以降の変数で値を指定できるようだ。

get_string('cclicensename','blocktype.${BTNAME}, 'BY-SA');

データベース

Viewに配置されたblocktype (instanse)は、block_instanse.config テーブルの configdata に設定データを保存できる。これ以外に、blocktypeに固有のデータベーステーブルを作りたい場合は

  • db/install.xml

にXMLDBの形式でスキーマを定義する。すると、管理者がプラグインをインストールしたときに、テーブルが作成される。テーブルを削除するための方法は提供されていない。以下、XMLDBのサンプル(blocktype/externalfeed/db/install.xml より)

<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="lib/db" VERSION="20060926" COMMENT="XMLDB file for core Mahara tables"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
    <TABLES>
        <TABLE NAME="blocktype_externalfeed_data">
            <FIELDS>
                <FIELD NAME="id" TYPE="int" LENGTH="10" SEQUENCE="true" NOTNULL="true" />
                <FIELD NAME="url" TYPE="text" NOTNULL="true" />
                <FIELD NAME="insecuresslmode" TYPE="int" LENGTH="1" SEQUENCE="false" NOTNULL="true" DEFAULT="0" />
                <FIELD NAME="content" TYPE="text" LENGTH="big" NOTNULL="false" />
                <FIELD NAME="lastupdate" TYPE="datetime" NOTNULL="false" />
            </FIELDS>
            <KEYS>
                <KEY NAME="primary" TYPE="primary" FIELDS="id" />
            </KEYS>
        </TABLE>
    </TABLES>
</XMLDB>

PHPのコードからデータベースにアクセスするには XMLDB の関数を使う。プラグインの場合は、データベースへの接続はMaharaが済ませてくれているはずなので、単に下記の関数を呼び出すだけである。

任意のSQLを実行

string execute_sql($command, $values=null);

$valuesに値を指定すると、prepare+execute する。

レコードの存在を確認する

bool record_exists($table, $field1=null, $value1=null,$field2=null,value2=null, $field3=null, $value3=null);
bool record_exists_select($table, $select='', $values=null);
bool record_exists_sql($sql, $values=null);

record_exists_select の $select には、where 句の中に入る条件式を書く。

レコードの行数をカウントする

int count_records($table, $field1=null, $value1=null, $field2=null, $value2=null, $field3=null, $value3=null);
int count_records_select($table, $select='', $values=null, $countitem='COUNT(*)');
int count_records_sql($sql, $values=null);

レコードを1行取得する

object get_record($table, $field1, $value1, $field2=null, $value2=null, $field3=null, $value3=null, $fields='*');
object get_record_sql($sql, $values=null);
object get_record_select($table, $select='', $values=null, $fields='*');

レコードを複数行取得する

ADOdb_obj get_recordset($table, $field='', $value='', $sort='', $fields='*', $limitfrom='', $limitnum='');
ADOdb_obj get_recordset_select($table, $select='', $values=null, $sort='', $fields='*', $limitfrom='', $limitnum='');
ADOdb_obj get_recordset_sql($sql, $values=null, $limitfrom=null, $limitnum=null);

hash  get_records_assoc($table, $field='', $value='', $sort='', $fields='*', $limitfrom='', $limitnum=''); 
array get_records_array($table, $field='', $value='', $sort='', $fields='*', $limitfrom='', $limitnum='');
hash  get_records_select_assoc($table, $select='', $values=null, $sort='', $fields='*', $limitfrom='', $limitnum='');
array get_records_select_array($table, $select='', $values=null, $sort='', $fields='*', $limitfrom='', $limitnum='');
hash  get_records_sql_assoc($sql,$values, $limitfrom='', $limitnum='');
array get_records_sql_array($sql,$values, $limitfrom='', $limitnum='');'

get_recordset* は ADOdb のオブジェクトを返す。Codezinの記事 参照。

*_assoc はハッシュを返す。ハッシュのキーは、最初のフィールドの値。UNIQ で NONNULL でない場合、行が失われる可能性があることに注意。 [#d79b35b6]

「メニュー」の関数?

hash get_records_menu($table, $field='', $value='', $sort='', $fields='*');
hash get_records_select_menu($table, $select='', $values=null, $sort='', $fields='*');
hash get_records_sql_menu($sql,$values=null);

これらの関数は、最初の二つのフィールドの値を関連づけるようなハッシュを返す。最初のフィールドがキーとなり、二つ目のフィールドがキーに対応する値となる。なぜメニューとよぶのか?

フィールド一つを取り出す

mixed get_field($table, $field, $field1=null, $value1=null, $field2=null, $value2=null, $field3=null, $value3=null);
mixed get_field_sql($sql, $values=null);

mixed get_column($table, $field, $field1=null, $value1=null, $field2=null, $value2=null, $field3=null, $value3=null);
mixed get_column_sql($sql, $values=null);

get_field* は、特定のフィールドの値を一つ取り出し、get_column* は特定のフィールドを全て返す。

フィールド一つの値をセットする

mixed set_field($table, $newfield, $newvalue, $field1=null, $value1=null, $field2=null, $value2=null, $field3=null, $value3=null);
mixed set_field_select($table, $newfield, $newvalue, $select, $values);

レコードの削除

mixed delete_records($table, $field1=null, $value1=null, $field2=null, $value2=null, $field3=null, $value3=null);
mixed delete_records_select($table, $select='',$values=null);

レコードの挿入と更新

mixed insert_record($table, $dataobject, $primarykey=false, $returnpk=false);
mixed update_record($table, $dataobject, $where=null);
mixed ensure_record_exists($table, $whereobject, $dataobject, $primarykey=false, $returnpk=false);

ensure_record_exists は、レコードがなければinsert、あればupdateを行う。

lib.phpでのクラス定義

PluginBlockType もしくは SystemBlockType のサブクラスとして PluginBlockType${BTName} を定義する。

PluginBlockType も SystemBlockType も blocktype/lib.php で抽象クラスとして定義されている。

abstract class PluginBlockType extends Plugin
abstract class SystemPluginBlockType 

PluginBlockType は、get_artefact と artefactchooser_elements を実装(空を返す)しているだけ。

blocktype 以下にインストールされているものはすべて SystemBlockType。

artefact/*/blocktype 以下にインストールされているものは、taggedposts を除きすべて PluginBlockType である。

メソッドはすべて public static で宣言する。

必ず実装しなくてはならないメソッド

get_title()

プラグインアイコン領域に表示されるタイトルを返す。このメソッドは必ず実装しなくてはならない。

get_description()

プラグインアイコン領域に表示される説明を返す。このメソッドは必ず実装しなくてはならない。

moodle_plugin-20121207-034550.png

get_categories()

プラグインアイコンがどのカテゴリで表示されるか。以下の6つのうちの一つを文字列で戻す。これらのカテゴリは maharadb の blocktype_category テーブルで定義されている。このメソッドは必ず実装しなくてはならない。

戻り値カテゴリ(日本語表記)
fileimagevideo「ファイル、イメージおよびビデオ」
blog「日誌」
general「一般」
internal「プロファイル」
resume「レジュメ」
external「外部コンテンツ」

render_instance(BlockInstance $instance, $editing=false)

ブロック枠内に表示すべきHTMLコードを返す。これが本質的。このメソッドは必ず実装しなくてはならない。

PluginBlockType の場合のみ実装するメソッド

artefactchooser_element($default=null)

artefact を選択するのに Pieform の artefactchooser を使う場合は、その定義をこの関数が返すようにする。ページネーションのために使う。PluginBlockTypeでは必ず実装しなくてはならない。

get_artefacts(BlockInstance $instance)

ブロックに関連している artefact の ID のリストを返す。view_artefact テーブルを作るのにも使われている。

デフォルトの動作としてconfigに保存されているartefactidを返すようになっているので、その動作で良い場合には実装する必要はない。

Cache Rebuilder というのが動いているので、保存するのは "top level artefacts" だけでよい。

プラグインのふるまいを規程するメソッド

single_only()

同一ビュー内に一つしか配置できないようにするには、このメソッドでtrueを返す。

allowed_in_view(View $view)

特定の条件で使えなくする場合には、ここでfalseを返すように実装する。falseを返すと、プラグインアイコン領域に表示されなくなる。配置済みのブロックには影響しない。

myviewなどでは、グループのviewで表示されないようにするため、viewのownerがnullかどうかを判定条件としている。

delete_instance(BlockInstance $instance)

ブロックが削除されるときに何か特別なことがしたい場合は、これを実装する。

get_viewtypes()

特定の種類のviewにしか置けないようにしたい場合には、これを実装する。viewの種類には、portfolio, dashboard, profile, grouphomepage がある。dashboard と portfolio にしか置けないようにしたい場合には、以下のようにすればよい。

return array('dashboard', 'portfolio');

タイトル関連のメソッド

override_instance_title(BlockInstance $instance)

配置されたブロックインスタンスのタイトルを書き換える。表示している人によってタイトルを変える時なんかに使っているようだ。

hide_title_on_empty_content()

中身がないブロックのタイトルを表示しない(デフォルトは「する」)場合には、falseを返すようにする。

has_title_link()

タイトルをクリックして、artefact表示に行く場合にtrueを返す。デフォルトはtrue

インスタンス設定関連のメソッド

has_instance_config()

ブロックインスタンスの設定を持つかどうか。true/falseを返す。

instance_config_form(BlockInstance $instance)

ブロックインスタンスの設定ダイアログに表示する項目を返す。pieformへの入力になる???

instance_config_save($values)

instance_config_form で設定された値が連想配列 $value として送られてくる。この関数で何か処理をして、 $values を返すと、その後で本来の保存処理をおこなう。

instance_config_validate(Pieform $form, $values)

Pieformの値検査をカスタマイズしたい場合にはこれを実装する。

Viewのコピーやエクスポートに関連するメソッド

default_copy_type()

LEAN2Aにエクスポートする時や、viewがコピーされる時、ブロックインスタンスがどのようにコピーされるのかを指示する。

戻り値(文字列)コピーの振る舞い
fullコンフィグはそのままコピーされる。関連するartefactidは、複製がつくられ新しいものとなる。
referenceコンフィグはそのままコピーされる。関連するartefactidもそのまま保持される。
shallow同じタイプのブロックをコピー先に作るが、コンフィグは rewritre_blockinsntace_config で変換した結果となる
nocopy新しいビューに、ブロックは含まれない

コピー元とコピー先の所有者が同じ場合には、reference が常に使われる。デフォルトは 'shallow'

rewrite_blockinstance_config(View $view, $configdata)

viewのコピーに伴って、インスタンスコンフィグを書き換えたい場合は、ここで実装する。

export_blockinstance_config(BlockInstance $bi)

export_blockinstance_config_leap(BlockInstance $bi)

import_create_blockinstance(array $biconfig, array $viewconfig)

Javascript 関係のメソッド

get_instance_javascript(BlockInstance $instance)

viewの表示の際に必要なJavascriptのパスを返す。lib.php からの相対パスでよいみたい。

get_instance_config_javascript(BlockInstance $instance)

instance configの表示の際に必要なJavascriptのパスを返す。lib.php からの相対パスでよいみたい。

get_instance_inline_javascript(BlockInstance $instance)

ブロックが表示されるときに実行したいスクリプトを(ファイル名ではなくコードの状態で)返す。

管理者のプラグイン管理画面関連のメソッド

has_config()

管理者のプラグイン管理画面で、設定項目があるか。true/falseを返す

get_config_options()

管理者のプラグイン管理項目の設定項目を返す。pieformの項目の形みたい。

save_config_options()

管理者のプラグイン管理項目を保存する。set_config_plugin を使う。

postinst($prevversion)


トップ   差分 バックアップ リロード   一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2013-08-19 (月) 00:40:30 (1527d)