PluginAPIStats

提供: GeeklogJpWiki

ここでは，サイトの統計情報が要求されたときに，どのようにしたらプラグインがGeeklogに統計情報を返せるようになるかについて説明しています。サイトの統計情報ページは2つの主要なセクションに分かれています。最初のセクションは統計ページの上部にあり，サイトの要約された情報を表示するのに使用されます。残りの部分は，Geeklogの各コンポーネントに関する詳細情報を表示するのに使用されます。2つのセクション共にあるいは一方のセクションにだけ表示される統計情報を返すよう，プラグインを書くことができます。

トップにあるサイトの統計情報要約ブロックには，プラグインの状況全体を要約するカウンタとして1行分の情報が表示されるでしょう。contactsプラグインの連絡回数やファイル管理プラグインのファイル数やプラグイン用の全般的なイベントカウンタが表示されるかもしれません。カウンタ数と説明を返す単純なデータベースへのクエリでこれは実現されるでしょう。

詳細統計情報セクションを使うと，統計ページ内にプラグイン用のブロックを持つことができ，好きなだけ詳細なレポートを行えます。たとえば，静的ページプラグインとファイル管理プラグインはそれぞれ，上位10位のページとファイルを表示します。

プラグインがGeeklogへの統計情報報告に要するプラグイン関数は1つだけです。このセクションで説明のために使用し，このキットの中に含まれる例題の関数は十分詳細な情報を提供するはずです。この関数を実装する次のプラグインもご覧ください。

静的ページ 1.2	要約と詳細をレポートする
ファイル管理 v1.2	要約と詳細をレポートする
Contact管理 v1.0	要約，つまり，合計の Contactのみレポート
Chatterblock 3.0	要約，つまり，チャットのレコード数だけレポート

次の表は関数の概要です。

	関数	関数の説明
1	plugin_showstats_{plugin}	この関数は，サイトの統計情報を拡張し，プラグインが提供する統計情報の要約か詳細かを指示するパラメータと共に呼び出される。何もレポートするものがないときには，空白 ' ' を返してもよい。

統計関数の呼び出し方

プラグインの functions.inc ファイルの中に既に完成されている showstats 関数を含めるだけです。標準的な関数命名規約に従うようにしてください。サイトの統計情報ページが作成されるときにGeeklogのstats.phpから自動的に呼び出されます。この関数には1個の整数型のパラメータ $showsitestats があり，要約の場合は 1 を，詳細の場合は 2 を指定します。

stats.phpの中では，PLG_getPluginStats() プラグインAPIが2回呼ばれます。呼ばれるたびに有効になっているプラグインが統計情報を返し，フォーマットされて最終的なページが出来上がります。

統計機能の一方にしか結果を返さなくても構いません。たとえば，Chatterblockプラグインは統計の要約しか返しません。

プラグインのデータベース変更

このAPIでは，データベースの変更やプラグインのテーブルは必要ありません。

関数の詳細と例

このサンプルの関数はファイル管理プラグイン v1.2から採ったもので，静的ページの検索関数と似ています。きちんとフォーマットされた結果を stats.php に返すために Geeklog のテンプレートクラスを使用します。

渡された整数型のパラメータが 1 の場合，この関数は要約レベルの値を返します。このプラグインを含めてほとんどのプラグインでは，プラグインが持つレコードの総数になるでしょう。表示する文字列には言語ファイルの変数を使用すべきです。

この時点でプラグインがレポートする統計がなければ，空の結果，つまり，"" を返します。

詳細なレポートを行うのは少し難しいです。ファイル管理プラグインと静的ページプラグインでは，詳細レポートでアクセスされたレコードの上位10位を返します。レポートするのに必要なデータがなければ，プラグインにロジックを追加しなければなりません。

たいていの場合，プラグインのレコードにそのデータがあるでしょう。この例では，SQL文がほとんどの作業をこなし，アクセス上位10位のレコードを返します。その後で検索結果が 0 件より大きいことを確認し，ループを回して1行ずつ最終的な結果を示す行をフォーマットするロジックを組むことになります。

統計用のテンプレートには，item_label, stat_name, item_url, item_text, item_stat などの多数の定義済み変数があり，各レコードの結果がセットされます。この場合は，アクセスのあったファイルの上位10位です。使用されている2つのテンプレートは <テーマ名>/stats の下にある itemstatistics.thtml と singlestat.thtml です。

詳細統計のセクションは，結果の項目ごとに item_url を伴う形で表示されます。これによりユーザは即座に統計レポートページからその項目にアクセスできます。item_url テンプレート変数にはその項目を見るためのURLがセットされます。

function plugin_showstats_filemgmt($showsitestats) {
  global $LANG_FILEMGMT, $_FM_TABLES, $_CONF;

  $stat_templates = new Template($_CONF['path_layout'] . 'stats');
  $stat_templates->set_file(array('itemstats'=>'itemstatistics.thtml', 'statrow'=>'singlestat.thtml'));
  if ($showsitestats == 1) {
    $total_pages=DB_count($_FM_TABLES['filemgmt_filedetail']);
    $total_downloads=DB_getItem($_FM_TABLES['filemgmt_filedetail'], 'SUM(hits)',"");
    $retval  = "<table border = '0' width='100%' cellspacing='0' cellpadding='0'>";
    $retval .= "<tr><td>" . $LANG_FILEMGMT['nofiles'] . "</td>";
    $retval .= "<td align='right'>" . $total_pages . " (" .$total_downloads .")
  } else {
    $result = DB_query("SELECT lid, title, hits from {$_FM_TABLES['filemgmt_filedetail']} WHERE hits > 0 ORDER BY hits desc LIMIT 10");
    $nrows = DB_numRows($result);
    $retval .= COM_startBlock($LANG_FILEMGMT['StatsMsg1']);
    if ($nrows > 0) {
      $stat_templates->set_var('item_label',"Page Title");
      $stat_templates->set_var('stat_name',"Hits");
      for ($i = 0; $i < $nrows && $i < 10; $i ++) {
        list ($lid, $title,$hits) = DB_fetchARRAY($result);
        $stat_templates->set_var('item_url', $_CONF[site_url]. "/filemgmt/singlefile.php?lid=".$lid);
        $stat_templates->set_var('item_text', $title);
        $stat_templates->set_var('item_stat', $hits);
        $stat_templates->parse('stat_row','statrow',true); 
      }
      $stat_templates->parse('output','itemstats');
      $retval .= $stat_templates->finish($stat_templates->get_var('output'));
    } else {
      $retval .= $LANG_FILEMGMT['StatsMsg2'];
    } 
    $retval .= COM_endBlock();
  }
  return $retval;
}