====== Admin Plugins ======

Admin PluginはDokuwikiの追加機能プラグインです。管理ページからアクセスすることができます。

Admin pluginのより詳細な情報は[[Admin Plugins|tutorial]]を参照してください。

===== 概要 =====

例えば、Admin Plugin //example//という名前のプラグインであれば''admin_plugin_example''という名前のクラスを必要とします。これは''DokuWiki_Admin_Plugin''を継承したクラスです。((''lib/plugins/admin.php''で定義されています。)). このクラスは''lib/plugins/example/admin.php''というファイルの中に記述されていなければなりません。プラグインとそのファイルの詳細は [[plugin file structure]]を参照してください。

最低でも以下の３つの関数を定義してください:

  * ''getInfo()'' --- プラグイン情報のハッシュを返す[author, email, date, name, dest, url]
  * ''handle()'' --- プラグインから要求された処理を実行する（？）
  * ''html()'' --- HTMLを出力する（？）

\\
以下のメソッドをオーバーライドすることができます:

  * ''forAdminOnly()'' --- プラグインが管理者からのみアクセス可能であれば''true''を返す。([[ ja:config:superuser|$conf['superuser'] ]]で設定されています). Wiki managersからアクセス可能であれば''false''を返す。([[ja:config:manager|$conf['manager'] ]]で設定されています). このメソッドはmanagerからアクセス可能にしたいときだけオーバーライドしてください。基底クラスは''true''を返します。
  * ''getMenuText($language)'' --- 管理者メニューで表示させたい文字列を返す。 [[#localisation guidelines]]に沿って開発された場合はオーバーライドする必要はありません。 外国語対応の文字は ''%%$lang['menu']%%''変数によって提供されます。これはプラグインの''lang/[language]/lang.php''の中にあります。
  * ''getMenuSort()'' 管理メニューの中のどの位置にプラグインのメニューを表示するのかを決める数字を返す。

追加の関数を定義することもできます。関数名の衝突をさけるために、関数名の前にアンダースコアをつけることをおすすめします。

\\ 
継承される関数とプロパティ

  * ''getLang($string_name)'' --- 現在の言語ローケルでの $string_name を返す。 [[#localisation guidelines]]を参照。
  * ''locale_xhtml($id)'' --- 即時出力のために、ローカルバージョンファイル''$id.txt''を渡す。
  * ''%%email($email, $name='', $class='', $more='')%%'' --- 適宜フォーマットされた ''mailto:''を
返す。 link, taking into account the wiki installation's ''mailguard'' setting.
  * ''%%external_link($link, $title='', $class='', $target='', $more='')%%'' --- 適宜フォーマットされた外部リンクを返す。 taking into account wiki config settings.
  * ''%%render($text, $format='xhtml')%%'' --- will pass $text to the parser & renderer for immediate output.  The text may contain DokuWiki markup. Use this sparingly as there is a large overhead in setting up the parser for each use.

===== 対ユーザ処理 =====
**(regaining control from Dokuwiki)**

ユーザーは管理ページのプラグインメニューオプションをクリックすることで、プラグインを使用します。
もしプラグインが、ユーザーからフォームやリンクを通してデータを受け取るのであれば、  
そこに下記の''$_REQUEST''変数が設定されていなければなりません。

  * ''%%$_REQUEST['do'] = 'admin'%%'' --- 管理者モードであるかどうかをDokuwikiに伝えます。
  * ''%%$_REQUEST['page']%% = //plugin name//'' --- どのプラグインをコールすべきかをDokuwikiに伝えます。存在しない場合には管理メニューが表示されます。
  * ''%%$_REQUEST['id']%% = //page name//'' --- 現在のページ。ユーザーが表示をクリックしたときにこのページが表示されます。


最も良い方法は、プラグインのHTML内でformにhiddenパラメータを設定することです。(''<input>'' with ''type="hidden"'')
またはクエリースとしてリンクから送ることもできます。


===== 他国語対応のガイドライン =====

Admin pluginの基本クラス(DokuWiki_Admin_Plugin)は多国語対応の機能も提供しています。４つのパブリックメソッドと２つのプロパティがあります:

  * **メソッド**
    * ''getLang('string name')'' --- will return the local language version of ''string name'' or the US English version if it is not present.
    * ''locale_xhtml('filename')'' --- will pass the local language version of ''%%'filename.txt'%%'' to the renderer for immediate output. If a local language file does not exist the US English version will be used.
    * ''localFN('id')'' --- will return the full path for local language file ''%%'id.txt'%%'' or if that file doesn't exist it will return the full path for the US English version of ''%%'id.txt'%%''.
    * ''setupLocale()'' --- will read in the plugins language strings for the current language - any missing strings will be filled with the US English version.  If retrieval of language strings is handled by ''getLang()'' there is no need to access this method.
  
  * **プロパティ**
    * ''$lang'' --- an array of language dependent strings. This array is initially empty and needs to be filled either by calling ''setupLocale()'' or making a call to ''getLang()''.  If all retrieval of language strings is handled by ''getLang()'' there is no need to access this property.
    * ''$localised'' --- boolean, indicates whether or not localisation has been setup.  Initially false, set to true by ''setupLocale()''. If all retrieval of language strings is handled by ''getLang()'' there is no need to access this property.

\\
言語ファイルは以下のように設置してください。


  lib/plugins/[プラグイン名]/lang/[xx]/

[xx]は２文字の国コードです。最低でも"en" (US English)の言語ファイルがなければなりません。このファイルは、対応する言語ファイルが存在しない時にも使われます。

プラグインで表示する文字列は以下のファイルで定義してください。

  .../lang/[xx]/lang.php

書き方はこのようになります。

  $lang['string name'] = 'text';

===== その他 =====

Admin pluginはDokuwiki管理者とフォームやクエリー文字列を通してやりとりします（$_REQUEST, $_POST or $_GET）。正しくないデータが送られてくることも想定して処理してください。悪意あるユーザーがサーバーやWikiの脆弱性を突いてくる可能性もあります。

A plugin may vary its menu text on the main admin menu depending on its status or the state of what it administers.


===== Admin Pluginサンプル =====

[[plugins:admin_skeleton|もう少し肉付けされたサンプル]]もあります。

''lib/plugin/skeleton/admin.php''
<code php>
<?php
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'admin.php');

/**
 * All DokuWiki plugins to extend the admin function
 * need to inherit from this class
 */
class admin_plugin_skeleton extends DokuWiki_Admin_Plugin {

    /**
     * return some info
     */
    function getInfo(){
      return array(
        'author' => 'me',
        'email'  => 'me@somesite.com',
        'date'   => '20yy-mm-dd',
        'name'   => 'admin plugin skeleton',
        'desc'   => 'demonstration skeleton',
        'url'    => 'http://www.dokuwiki.org/plugin:admin',
      );
    }

    /**
     * return sort order for position in admin menu
     */
    function getMenuSort() {
      return 999;
    }

    /**
     * handle user request
     */
    function handle() {
    }

    /**
     * output appropriate html
     */
    function html() {
    }

}</code>

''lib/plugins/skeleton/lang/en/lang.php''
<code php>
<?php
/**
 * english language file
 */

// settings must be present and set appropriately for the language
$lang['encoding']   = 'utf-8';
$lang['direction']  = 'ltr';

// for admin plugins, the menu prompt to be displayed in the admin menu
// if set here, the plugin doesn't need to override the getMenuText() method
$lang['menu'] = 'Skeleton Plugin...'; 

// custom language strings for the plugin
</code>