|
| Geeklogドキュメント HOME - プラグイン開発 |
Geeklogは日々人気を得てきており、我々Geeklogの開発者は時に利用者の方がそれぞれのニーズに応じて、Geeklogを拡張するためにしている素晴らしいハックの数々に驚かされます。同時にGeeklog開発チームも少しでもGeeklogがよくなるようにと、新機能を継続して付け足しています。Geeklogが２種類の開発をサポートする必要があることに気が付きました。すなわち、Geeklogのコアコードとプラグインコードです。プラグインを利用してGeeklogの機能を拡張するために必要な基礎構造を構築することによって、Geeklogのコードとプラグインのコードを完全に分離することができます。それによって我々はGeeklogのコアのコードを改良することに専念し、ニーズに合わせてプラグインが開発できるようになります。Geeklogはプラグインのためのアプリケーションプログラムインターフェース（API)を持つようになったのです。
アプリケーションレベルではGeeklogプラグインAPIはGeeklogコアの戦略的な場所でプラグイン関数を呼び出されせるようにするgenericコードです。
これにより次の機能がプラグインで使えるようになります。
- ユーザがプラグインにオブジェクトを投稿できるように投稿機能をプラグインに付け加えることができます。プラグインに投稿されたデータをモデレートするためにGeeklogに備えられたコマンドおよびコントロールを活用すればよいでしょう。
- Geeklogの各ページに管理者ブロックとユーザブロックを表示させることができます。
- Geeklogの検索ページから検索できるようにします。
- スタッツのページにプラグインのスタッツが表示されるようにします。
- Geeklogのコメントエンジンを利用できるようにします。
- プラグインのプログラムでGeeklogのライブラリ（lib-common.php）を利用できるようにします。
- プラグインの実現する機能に制限を設けません。プラグインに制限をかけることはありません。
次の関数は全ての引数を含め自身のプラグインを書くために必要な関数です。
このページの終わりまで、プラグインがどう処理されるのかを理解する必要ができた場合に備えてAPIの説明があります。プラグイン名<plugin name>に関する注意：以下の関数には<plugin name>という参照があります。<plugin name>の値は、あなたの決めた圧縮ファイルの名称からきます。全てのプラグインの圧縮ファイルには従わなければならない次のような命名規則があります。
<plugin name>_<plugin version>_<geeklog version>.tar.gz
e.g. photos_1.0_1.3.tar.gz
まず、現在のGeeklogのcodebaseでは投稿に用いられるプラグインテーブル名を指定の方法で名づけることが強制されるという制限があることに注意してください。全ての記事やリンクといったモデレートされるGeeklogのアイテムは２つのテーブルから構成されています。最初のテーブルはメインテーブルで全ての表示される情報が保存されます。２番目のテーブルは投稿テーブルで投稿された情報が管理者の承認を得るまで保存されています。認証されれば、その情報は投稿テーブルからメインテーブルに移動します。例えば、ユーザがブックレビューを投稿できるbook reviewプラグインを書いていて、メインテーブル名をbookreviewsとするとします（この名前はプラグインの名前と同じである必要があります）。その場合には投稿テーブル名はbookreviewssubmissionと名づけられなければなりません。なぜ名前を強制するのでしょう。Geeklogのコードでは全ての記事の投稿テーブルは<main name>submissionと名づけられているからです。それでメインテーブル（そしてプラグイン名）にbookreviewsという名称をつけたら、投稿テーブルはbookreviewssubmissionと名づけられる必要があります。
Geeklogの記事やリンクのようにモデレートできるようにする場合は次のような関数を実装しなければなりません。
| 関数 | 関数の説明 |
|---|---|
| plugin_submit_<plugin name> | プラグインの投稿フォームを表示します。 |
| plugin_itemlist_<plugin name> | moderation.phpでモデレーションが必要なプラグインの項目を表示します。 |
| plugin_savesubmission_<plugin name> | ユーザの投稿を<plugin name>submissionテーブルに保存します。 |
| plugin_moderationdelete_<plugin name> | <plugin name>submissionテーブルからIDで検索して削除します。 |
| plugin_moderationapprove_<plugin name> | <plugin name>submissionテーブルからIDで検索してメインの<plugin name>テーブルに移動します。 |
| plugin_moderationvalues_<plugin name> | モデレーションページで表示したいテーブルのprimaryキーカラム名、テーブル名（<plugin name>）、フィールドのリストを返します。 |
Geeklogの各ページに表示する管理者メニューおよびユーザ関数ブロックを変える場合は、次のような関数を実装する必要があります。
| Function | Description of Function |
|---|---|
| plugin_adminoptions_<plugin name> | プラグインの管理者ファンクションブロックの下にオプションを表示します。 |
| plugin_getuseroption_<plugin name> | プラグインのユーザファンクションブロックの下にオプションを表示します。 |
| plugin_adminedit_<plugin name> | admin/plugins/<plugin name>.phpのトップに新規投稿と管理者ホームページへのリンクを表示します。以前のバージョンと一貫性を保つための関数です。 |
| plugin_submissioncount_<plugin name> | プラグインで承認待ちになっている投稿数を表示します。通常 |
| plugin_cclabel_<plugin name> | プラグイン画像とラベルの配列を返します。moderation.phpのコマンド＆コントロールブロックにプラグインを表示させます。 |
プラグインを検索可能にするには、次の機能を実装してください。
| Function | Description of Function |
|---|---|
| plugin_getsearchtypes_<plugin name> | search.phpのTypeに関するドロップダウン選択肢に新しいタイプを付加したいと思うでしょう。この関数は必要となるオプションタグを出力します。valueタグが<plugin name>になっていることを確認してください。 |
| plugin_dopluginsearch_<plugin name> | 検索条件を取り込んでプラグインの検索結果を構築する。この関数はテーブルの行の文字列の配列を返します。検索結果の各レコードが一行になります。 |
プラグインでコメントをサポートし、Geeklogのコメントエンジンを利用したければ、プラグインのfunction.incファイルで次の機能を実装する必要があります。
| Function | Description of Function |
|---|---|
| plugin_commentsupport_<plugin name> | この関数は引数をとりません。このプラグインがコメントをサポートするのであれば単にtrueを返します。Geeklogコード（例：article.php）で呼ばれプラグインへコメントの扱いを処理させるかどうかを決定します。 |
| plugin_handlecomment_<plugin name> | この関数はcomment id（commentテーブルでのprimaryキー）、コメントへの操作のタイプ（'save'または'delete'）を引数とします。プラグインの項目に対するコメントの総数を更新し、ページを更新するか、あるいはサイトのメインページではなく、プラグインのページにリダイレクトします。 |
| plugin_commentform_<plugin name> | この関数は複数のパラメータが必要でGeeklogのarticle.phpとcomment.phpから呼ばれます。引数はcomment_id（primaryキー）、comment_mode（nested, flat, threaded, none, ）、order（Ascending、Descending）、reply（コメントバーの投稿ボタンが押された時の答え）になります。comment_idだけが必須です。 |
| plugin_commentparent_<plugin name> | plugin_commnentform関数から呼び出されるオプション関数でコメントの親に当たるプラグインの項目を表示します。これがGeeklogが記事とコメントバー、関連するコメントを同時に表示する仕組みです。 |
プラグインの情報がスタッツページに表示されるようにするには、次の機能を実装する必要があります。
| Function | Description of Function |
|---|---|
| plugin_showstats_<plugin name> | この関数はshowsitestatsフラグを引数にとります。フラグが１に設定されていれば、この関数はサイトの統計ボックスにプラグインの総合スタッツを表示します。２に設定されていれば、プラグインの（参照数上位10の記事、コメント数上位10の記事のような）スタッツブロックを表示します。 |
アンインストール機能をプラグインに付ける場合は、次の機能を実装する必要があります。
| Function | Description of Function |
|---|---|
| plugin_uninstall_<plugin name> | この関数は引数をとりません。プラグインは自分自身をアンインストールし、特にデータベースから関連するテーブルを削除する必要があります。 アンインストールが成功すればtrue、失敗すればfalseを返します。 |
いくつかのプラグインではユーザアカウントの生成と削除をたどる必要があるでしょう。
| Function | Description of Function |
|---|---|
| plugin_user_create_<plugin name> | この関数は新規のユーザアカウントが作成された時に呼ばれます。渡される引数はユーザIDだけです。値は返しません。 |
| plugin_user_delete_<plugin name> | この関数はユーザアカウントが削除されたときに呼ばれます。渡される引数はユーザIDだけです。値は返しません。 |
プラグインでユーザプロファイルにブロックあるいは個別の情報を付け加えることができます。
| Function | Description of Function |
|---|---|
| plugin_profilevariablesedit_<plugin name> | この関数はGeeklogがユーザプロファイル用の編集フォームを表示する直前に呼ばれます。プラグインにはユーザIDと編集画面への参照が渡されます。これによってフォームにプラグイン独自の変数と入力フィールドを加えることができます。 |
| plugin_profileblocksedit_<plugin name> | この関数はGeeklogがユーザプロファイル用の編集フォームを表示する直前に呼ばれます。引数としてユーザIDをとります。プラグインはプロファイル編集フォームに表示されるようブロック用のHTMLを（ブロックヘッダとブロックフッタを含めて）返します。いくつかの項目をプラグインが要求する場合は、項目をこのようにグループ化するのが適切です。それ以外の場合は代わりにplugin_profilevariablesedit_<plugin name>（上記参照）を使います。 この関数はブロック用のHTMLか空文字列を返すようにします。 |
| plugin_profilevariablesdisplay_<plugin name> | この関数はGeeklogがユーザプロファイルを表示する直前に呼ばれます。引数としてユーザIDとプロファイルのテンプレートへの参照をとります。プロファイルに独自の変数を追加することができるようになります。 この関数は何も返しません。テンプレートに項目を加えるために（set_varなどの）テンプレート関数を使う必要があります。 |
| plugin_profileblocksdisplay_<plugin name> | この関数はGeeklogがユーザのプロファイルを表示する直前に呼ばれます。ユーザIDを引数にとり、プロファイルページに表示したい追加ブロックのHTMLを返します。 この関数はブロック用のHTMLか空文字列を返すようにします。 |
その他の目的のための（追加の）機能のリストを次に示します。
| Function | Description of Function |
|---|---|
| plugin_centerblock_<plugin name> | プラグインはサイトの中央部にブロックを表示できます。この関数はサイトのindexページをレンダリングする際に数回呼ばれます。引数によってindexページのどこにブロックを表示するか決まります。 引数は表示場所（１＝ページ最上部、２＝注目記事の後、３＝ページ最下部）、ページ番号、topic idとなります。表示場所については0をとることもできます。0の場合はプラグインがページ全体を置き換えてしまいます（この場合ページ全体のHTMLを返す必要があります。すなわちサイトのヘッダやフッタも含まれているHTMLです）。 この関数は（ヘッダ、フッタを含めた）完全なブロックのHTMLか空文字列を返します。 |
| plugin_getheadercode_<plugin name> | この機能を実装することでプラグインはサイトの<head>タグに行を追加できます。例えばJavascript関数や追加のメタタグなどです。 関数は追加のヘッダ行をすべて連結した文字列を返す必要があります。 |
| plugin_templatesetvars_<plugin name> | プラグインでテンプレート変数を追加できます。この関数は現在のところCOM_siteHeaderおよびCOM_siteFooterで呼ばれるだけですが、将来は他の場面でも呼ばれることになるでしょう。引数はテンプレート名とテンプレートオブジェクトへの参照です。このプラグインAPIはテンプレート名（現在のところ'header'か'footer'）をチェックしてテンプレートオブジェクトの参照を利用して要求のあったどのような新規の変数も設定します。 |
| plugin_whatsnewsupported_<plugin name> | プラグインはこの関数および以下の関数を実装することでGeeklogの新着情報ブロックに自身のセクションを追加することができます。 この関数は２つの文字列からなる配列を返します。最初の文字列は新着情報のプラグインセクションのヘッドラインとして使われます。２番目の文字列はこのセクションエントリが取り上げる期間を示します（例えば過去２週間）。 |
| plugin_getwhatsnew_<plugin name> | この関数は新着情報ブロックにリストアップされる新エントリ（配列として）か、エントリのない場合に表示される文字列を返します。 |
| plugin_chkVersion_<plugin name> | プラグインはバージョンを返すこの関数を実装する必要があります。新規のバージョンをリリースする前に簡単にバージョンを更新できるようにするため、プラグインのconfig.phpにある変数でバージョンを指定すべきです。Geeklog 1.3.10ではこのAPI関数はプラグインエディタで、現在インストールされているプラグインのバージョンとこれから入れようとしているプラグインのバージョンを表示するために呼ばれます。。このインストールされているプラグインのバージョンはpluginsテーブルから引き出され、プラグインのインストールや更新の際には更新されます。このAPI関数によって管理者はこれから入れようとしているプラグインが既にインストールされているバージョンより新しいかどうかを知ることができます。プラグイン開発者にとってはpluginsテーブルから既にインストールされたバージョンを知ることができ、自動的にSQLによる更新が必要かどうか、あるいは少なくともプラグインの新バージョンに対応するようプラグインレコードを更新べきかを決定することができます。 |
| plugin_runScheduledTask_<plugin name> | この関数によってプラグイン開発者が定期的にあるタスクを実行させるころができます。このAPIは誰かがサイトにアクセスしたときにのみ呼び出されますが、メンテナンスや このAPIが呼ばれる間隔はサイトのconfig.phpで設定され、この関数をもつ全てのプラグインがその間隔で呼び出されます。 |
以下はRSS配信用の（オプションの）関数のリストです。
| Function | Description of Function |
|---|---|
| plugin_getfeednames_<plugin name> | プラグインはRSS配信データを作成する情報を提供します。この関数によってプラグインが提供できる配信内容を返すことができます。例えば、リンクプラグインでは全てのリンクに対する配信データと各リンクカテゴリに対する配信データを提供します。プラグインはidとnameの配列を返します。idはフィールドを示すプラグイン内部のidでnameはユーザに表示されるものです。 |
| plugin_getfeedcontent_<plugin name> | プラグインがplugin_getfeednames_<plugin name>関数で配信データのリストを返す時には、この関数を使って配信内容を返す必要があります。プラグインは'link'（配信データにあるサイトの該当する内容を表すリンク）と'update_data'（後に最新かどうかのチェックをする時に必要）の２つの情報を提供するために、配信データの内容をもつ配列を返す必要があります。 |
| plugin_feedExtensionTags_<plugin name> | この関数をサポートすることで、配信フォーマットの最上位に要素を付け加えることができます。この関数は配信形式とバージョン（例えばRSS version 2.0）を受け取り、有効なXMLタグ配列を返します（例としてSyndication Extensionsプラグインを参照）。 |
| plugin_feedNSExtensions_<plugin name> | RSS配信に独自の要素を付け加えるプラグインはXMLに名前空間を付加する必要があるかもしれません。この関数は有効な名前空間の属性配列を返します（例としてSyndication Extensionsプラグインを参照）。 |
| plugin_feedElementExtensions_<plugin name> | プラグインはこの関数をサポートすることで配信項目に追加要素を含めることができます。配信データのバージョンと形式、内容の形式、識別子を引数にとり、整形式のXML要素の配列を返す必要があります。（例としてSyndication Extensionsを参照） |
GeeklogのプラグインAPIは単なるAPIです。当然ですがプラグインのプログラム自体は自分自身で書く必要があります。管理画面へのリンクはあらかじめ決められています。管理画面はhttp://yourgeeklogdomain/admin/plugins/<plugin name>/に置くようにしてください。
管理画面の最初のページはindex.phpである必要があります。adminディレクトリの一つ上のディレクトリになければなりません。管理画面として２ページ以上使うかどうかは自由に決めてください。
管理ページの場所は決まっていることに注意してください。プログラム構成を保つためにこの文書の標準的な指針に従うことが重要です。
プラグインのtar形式の圧縮ファイル
全てのGeeklogプラグイン圧縮ファイルは次の命名規則に従わなければなりません。
<プラグイン名>_<プラグインのバージョン>_<Geeklogのバージョン>.tar.gz
<plugin name>_<plugin version>_<geeklog version>.tar.gz
Descriptions
- <plugin name>:
- プラグイン名は次のような名前の制約を課しますので、プラグイン用に選ぶ値としては一番重要になります。
this is one of the single most important values you will choose for your plugin as it dictates the following:
- Geeklogがプラグインを呼び出す時のAPI関数の名前はこれと同一
- サイトディレクトリで全てのプラグインプログラムを置くディレクトリの名前はこれと同一
- サイトのadminディレクトリで全ての管理者用プログラムを置くディレクトリの名前はこれと同一
- モデレーションを使用する場合、モデレート対象となるメインテーブルの名前はこれと同一
- モデレーションを使用する場合、投稿テーブルの名前は<plugin name>submission
- <plugin version>:
- プラグインのインストール中にプラグインの更新をしようとしているのか新規インストールをしようとしているのかを決定するのに用います。新しいバージョンのプラグインが既にインストールされているのに旧バージョンをインストールしようとしていないかもチェックします。
- <geeklog version>:
- プラグインが動作しているGeeklogのバージョン
圧縮ファイルの構成も同様に標準化されます。各ディレクトリとファイルを説明します。圧縮ファイルを作成する時のプラグイン全体のディレクトリ名は<plugin name>でなければなりません。そのディレクトリ下には以下のものを置きます。
- config.php:
- プラグインの設定に関するファイル。config.phpを利用するのも問題ありません。このファイルはいつでも呼び出すことができます。制限はありません。
configuration page for your plugin. We'd prefer you to data-drive most the values if possible but using config.php is fine. This file can be called whatever you want...you are not restricted.- functions.inc:
- このファイルにGeeklogのAPIを実装し、プラグインの実際のプログラムもここにあります。このファイルはこの名前でなければなりません。lib-common.phpの最後で有効にされた全てのプラグインのfunciton.incファイルを読み込むからです。そのためプラグインのプログラムはlib-common.phpにある全ての関数にアクセスできる点に注目してください。
- lang.php or language/ directory:
- プラグイン用の言語ファイルです。このファイルをfuncitons.incに読み込む必要があります。
the language file(s) for your plugin. You should include this file in your functions.inc.
languageディレクトリを使ってサポートする各言語用の個別の言語ファイル（english.phpなど）を用意することを推奨します。Geeklogの振る舞いを習ってユーザの選択した言語に基づいて言語ファイルを選択します（選択した言語用の言語ファイルがなければenglish.phpが選択されます）。- README
- ソフトウェアの通常のREADMEファイルです。
- /docs:
- 履歴やTODOなどプラグインに添付したい文書を含みます。
- /admin:
- 管理ページのみを含みます。
- /public_html:
- 通常のWebページを含みます。
- /updates:
- 全ての更新のためのSQLとスクリプトを含みます。
同梱されているプラグインの他、たくさんのプラグインがいろいろなところで公開されています。 多くは英語なので、 言語ファイルの日本語版を用意してインストールします。
配布元 http://www.geeklog.net/ ほか
注意：Geeklog 1.3.4まではプラグインについては自動インストールができましたが、問題が多数ありサポートの問題もありましたので、その後のバージョンでは取り除かれました。後述に概要がありますが、手動インストールがプラグインをインストールする推奨方法で、Geeklogの旧バージョン・新バージョン共に利用できます。
詳細についてはプラグインに同梱されているREADMEを常に確認する必要があります。プラグインの一般的な概要とインストール手順の詳細はこのGeeklog文書プロジェクトの一部hereとして提供されます。一般的にはプラグインは次のような手順でインストールされます。
- セットアップとサーバアクセスによって異なりますが、tar形式の圧縮ファイルをサーバにアップロードしてサーバ上で解凍するか、先に解凍しておいてそれからアップロードします。
- 圧縮ファイル内のpublic_htmlディレクトリ：
サイトディレクトリの<plugin name>の下にコピーします。
例えば/path/to/geeklog/public_html/にGeeklogが導入されていれば、/path/to/geeklog/public_html/<plugin name>にpublic_htmlをコピーします。
圧縮ファイル内のadminディレクトリ：
サイトのadminディレクトリにコピーします。
例えば、/path/to/geeklog/public_html/admin/であれば/path/to/geeklog/public_html/admin/plugins/<plugin name>にadminディレクトリをコピーします。
一般的なプラグインのフォルダ・ファイル構成:
public_html/admin/plugins/<plugin name>/
public_html/<plugin name>/
private/plugins/<plugin name>/language/english.php
private/plugins/<plugin name>/sql/
private/plugins/<plugin name>/template/
private/plugins/<plugin name>/config.php,functions.inc他- プラグインのインストールスクリプトを実行します。
http://yourgeeklogsite/admin/plugins/<plugin name>/install.php
- 新規インストールの場合（プラグインがプラグインテーブルにない場合）、インストールスクリプトは必要なテーブルとデフォルトのデータを生成するインストール用SQLを実行します。
- アップグレードであれば、提供されるプラグインドキュメントを参照してください。最近のプラグインであればアップデートを行うためのプラグインAPIをサポートしているかもしれません。更新機能が利用可能であれば管理者はプラグインエディタで更新の実行できます。
- 一般的なプラグインを日本語で使うため、言語ファイルを設置する。
プラグインが日本語化されていない場合は、English.phpを元にjapanese.php（EUCの場合）またはjapanese_utf-8.php(URF-8の場合)を用意してください。なければ翻訳して作成します。日本語言語ファイルがない場合は、english.phpが参照されます。
GeeklogプラグインはGeeklogのインストールやファイルシステムに影響を与えるので、Geeklogの開発チームがテストするまではサードパーティのプラグインを推奨しないのが我々のポリシーです。我々は作成されたプラグインがうまくインストールされ、どのような副作用も生じさせないことを確認します。プラグインが問題ないとなれば、Geeklogユーザにダウンロードしてもらえるよう、我々のサイトにプラグインの圧縮ファイルをおきます。http://www.geeklog.netにプラグインを送信してください。
| Geeklog ドキュメントプロジェクト このページの全ての商標と著作権は、彼らのそれぞれの所有者によって所有される。 GeekLogは、コピーレフトです。 |