| ログ解析スクリプトAWStats 7.8ドキュメント |

# プラグインのフック

以下は、プラグイン開発者が利用できるフックのリストです。レポート作成や解析プロセスにおけるさまざまなステップで、AWStatsは一致するフック用のプラグインのリストをスキャンし、それらを実行します。すべてのフックはフックの名前で始まり、アンダースコアの後にプラグイン名が続きます。例えば、"mypluginname"と呼ばれるプラグインを作成していたのであれば、初期化フックは次のようになります

`sub Init_mypluginname()`

記載されていないフックが必要な場合は、Source Forgeを通じて開発者に連絡し、要求を提出てください。

- 必須フック
- 共通フック
- 処理/更新フック
- 出力/HTMLフック

## 必須フック

### Init_プラグイン名

- タイプ：All
- パラメタ：構成ファイルに定義されたパラメタ
- 呼び出し時期：構成ファイルをロードして、プラグインの指定を構文解析した後。構文解析やHTML出力の前。
- 説明：初期化のフックは構成ファイルからパラメータをロードし、他のフックが呼び出される前に、プラグインで使用する変数を初期化するために使用します。これは、必要なハッシュテーブルを初期化したり、データファイルをオープンするのに適した場所です。
- 注：Init_はAWStatsが使用するために、プラグインが実装するフックのリストを返す必要があります。次に例を示します。

  `sub Init_geoip_region_maxmind {
  my $checkversion=&Check_Plugin_Version($PluginNeedAWStatsVersion);
  return ($checkversion?$checkversion:"$PluginHooksFunctions");
  }`

  プラグインが、いくつかのパラメタを受け付ける場合は、次のような行を挿入します。

  `my $InitParams=shift;
  my ($mode,$datafile,$override)=split(/\s+/,$InitParams,3);`

  ローカル変数を検証し、読もうとするパラメタの数にあわせて分割数を変更してください。

## 共通フック

### SectionInitHashArray_プラグイン名

- タイプ：All
- パラメタ：なし
- 呼び出し時期：起動時や履歴ファイルのパージ時や処理中に新しい月が始まるときなど、AWStatsのInitHashが呼び出された場合。
- 説明：プラグインにローカルのハッシュ変数を初期化またはクリアするために使用します。

## 処理/更新フック

### SectionWriteHistory_プラグイン名

- タイプ：Update
- パラメタ：$xml, $xmlbb, $xmlbs, $xmlbe, $xmlrb, $xmlrs, $xmlre, $xmleb, $xmlee
- 呼び出し時期：AWStatsが履歴ファイルに書き込むたびに。
- 説明：プラグインが履歴ファイルにセクションを書くことができます。プラグインは、大量のデータを格納する場合、それが大幅に履歴ファイルのサイズを大きくし、読み込みと処理が遅くなる可能性があることに注意してください。このような状況では、個別の履歴ファイルに書き込むトリガーとしてこれを使用することができます。そして、そのデータの読み取りのトリガとしてSectionReadHistory_のフックを使用できます。
  XMLパラメータは、履歴ファイルが使用する事前定義されたXMLタグです。

### SectionReadHistory__プラグイン名

- タイプ：Update, Output
- パラメタ：$issectiontoload, $readxml, $xmleb, $countlines
- 呼び出し時期：AWStatsが履歴ファイルを読み込むたびに。
- 説明：プラグインが履歴ファイルに書きこんだセクションを読むことができます。履歴ログは常にログエントリを解析する前に、かつHTMLを出力する前にロードされます。
  - $issectiontoload - 履歴ファイルで検出されたプラグインセクションの名前。これがtrueの場合、プラグインは、フィールドのデータを処理する必要があります。
  - $readxml - 真の履歴ファイルはXML形式の場合true。
  - $xmleb - XML要素の開始タグ
  - $countlines - これまでの履歴ファイルから読み込まれている行数

### SectionProcessHostname_プラグイン名

- タイプ：Update
- 必須：No
- パラメタ：解決されたホスト名。
- 呼び出し時期：ログファイルの行を読み込みホスト名が解決された場合。
- 説明：www.google.comのような解決されたホスト名を処理し、ホストへのヒットを数えたり、追加の情報を調べるのに便利です。

### _プラグイン名

- タイプ：Update
- パラメタ：$Host
- 呼び出し時期：ログファイルの行を読み込みDNS解決がオフになっているか、ホストが解決されなかった場合
- 説明：192.168.1.1のようなIPアドレスを処理し、ホストへのヒットを数えたり、追加の情報を調べるのに便利です。

## 出力/HTMLフック

### AddHTMLMenuLink_プラグイン名

- タイプ：Output
- 必須：AddHTMLGraph_フック
- パラメタ：$categ, $menu, $menulink, $menutext
- 呼び出し時期：新しいメニューのカテゴリがナビゲーションフレームまたはセクションに出力される時。
- 説明：プラグインで定義されているAddHTMLGraph_フックにリンクするメニューアイテムをナビゲーション領域に挿入します。そのフックが定義されていない場合は、エラーとなります。AddHTMLGraph_フックが必要です。
  - $categ - "訪問者の属性"(who)や"アクセス状況"(navigation)といった、メインナビゲーションのカテゴリの名前
  - $menu - メニューのなかでリンクを表示する位置を返します。
  - $menulink - リンクのタイプの宣言を返します。
  - $menutext - ユーザーに表示するテキストを返します。

### AddHTMLGraph_プラグイン名

- タイプ：Output
- 必須：AddHTMLMenuLink_フック
- パラメタ：なし
- 呼び出し時期：AddHTMLMenuLink_が作成したリンクがクリックされ、HTMLヘッダが送信され、HTMLフッターが送信される前。
- 説明：ホストのレポートまたは地域のページのような、プラグインに固有の情報を持つ専用のレポートページを生成するために使用されます。標準のAWStatsのヘッダとフッタの間のHTMLについてプラグインの出力だけとなります。

### AddHTMLStyles_プラグイン名

- タイプ：Output
- パラメタ：なし
- 呼び出し時期：構成ファイルに特定のスタイルシートのURLを定義しないときにHTMLのヘッダーを出力する場合。
- 説明：このセクションを使用して、HTMLヘッダにスタイル情報を出力する。開始や終了のstyleタグ(つまり<style></style>)でなく、個々のスタイル定義のみを出力する。

### AddHTMLHeader_プラグイン名

- タイプ：Output
- パラメタ：なし
- 呼び出し時期：HTMLのヘッダーを出力していて、ヘッダを閉じる</head>タグの直前。
- 説明：プラグインは、javaスクリプトが含まれるかとかメタタグなどの余分なHTMLヘッダー情報を必要とする場合、このフック内でそれらを出力する。

### AddHTMLFooter_プラグイン名

- タイプ：Output
- パラメタ：なし
- 呼び出し時期：HTMLフッターの出力時。
- 説明：AWStatsの著作権およびクローズする</html>タグの前にフッターHTMLコードを出力。トラッキングコードやバナー広告を出力する必要がある場合に便利。

### AddHTMLBodyHeader_プラグイン名

- タイプ：Output
- パラメタ：なし
- 呼び出し時期：HTMLのヘッダーが出力された後。
- 説明：バナーやその他の情報が印刷される前に、メインのHTML本体に情報を出力するために使用。

### AddHTMLMenuHeader_プラグイン名

- タイプ：Output
- パラメタ：なし
- 呼び出し時期：HTMLヘッダとHTMLボディのヘッダの後。
- 説明：ページ上でインライまたはナビゲーションフレームンで、ナビゲーションメニューのヘッダーを出力するために使用。

### AddHTMLMenuFooter_プラグイン名

- タイプ：Output
- パラメタ：なし
- 呼び出し時期：HTMLナビゲーションメニューが出力された後
- 説明：ページ上でインライまたはナビゲーションフレームンで、ナビゲーションメニューのフッターを出力するために使用。

### AddHTMLContentHeader_プラグイン名

- タイプ：Output
- パラメタ：なし
- 呼び出し時期：HTMLナビゲーションメニューが出力された後
- 説明：ナビゲーションメニューの後に、すべてのレポートページのコンテンツのテーブルの前に出力。

### TabHeadHTML_プラグイン名

- タイプ：Output
- パラメタ：$title
- 呼び出し時期：新しくコンテンツのテーブルを始めたときに
- 説明：プラグインがデフォルトのテーブルヘッダのスタイルを上書きできます。一般的に使用されません。
  - $title - ユーザーに表示するタイトル

### ShowInfoHost_プラグイン名

- タイプ：Output
- パラメタ：$host
- 呼び出し時期：メインページのホスト名セクションまたはホスト名の全リストのページで、新しくホストの行が表示されたとき。
- 説明：ホストに関する詳細情報を記載するテーブルの列を表示するために使用されます。入力パラメタは3つの値のいずれかになります。
  - '__title__' - ヘッダ列を出力していることを示すリテラル値
  - 名前解決されたホスト名 - ホストの名前
  - IPアドレス - 名前未解決のドット付き10進IPアドレス

### ShowInfoUser_プラグイン名

- タイプ：Output
- パラメタ：$user
- 呼び出し時期：認証されたユーザの行が表示されるたび。
- 説明：ユーザーに関する詳細情報を持つテーブルの列を表示するために使用されます。入力パラメタは2つの値のいずれかになります。
  - '__title__' - ヘッダ列を出力していることを示すリテラル値
  - ユーザ - 認証されたユーザー名

### ShowInfoCluster_プラグイン名

- タイプ：Output
- パラメタ：$cluster
- 呼び出し時期：クラスタの行が表示されるたび。
- 説明：クラスタに関する詳細情報を持つテーブルの列を表示するために使用されます。入力パラメタは2つの値のいずれかになります。
  - '__title__' - ヘッダ列を出力していることを示すリテラル値
  - クラスタ - クラスタ名

### ShowInfoURL_プラグイン名

- タイプ：Output
- パラメタ：$url
- 呼び出し時期：ページURLや接続元URLの行が表示されるたび。
- 説明：URLに関する詳細情報を持つテーブルの列を表示するために使用されます。入力パラメタは2つの値のいずれかになります。
  - '__title__' - ヘッダ列を出力していることを示すリテラル値
  - URL - ページURLや接続元URL

### ShowInfoGraph_プラグイン名

- タイプ：Output
- パラメタ：$title, $type, $display, @blocklabel, @vallabel, @valcolor, @valmax, @valtotal, @valaverage, @valdata
- 呼び出し時期：HTMLにレポートやグラフが表示されるたび。
- 説明：チャートやグラフを表示するために使用されます。AWStatsは、グラフ作成プラグインが処理することができるデータ、色およびラベルの配列を生成します。詳細については、グラフのプラグインを参照してください。

### ShowPagesAddField_プラグイン名

- タイプ：Output
- パラメタ：$key
- 呼び出し時期：メインページや詳細ページでURLの行が表示されるたび。
- 説明：URLに関する詳細情報を持つテーブルの列を表示するために使用されます。入力パラメタは3つの値のいずれかになります。
  - '__title__' - ヘッダ列を出力していることを示すリテラル値
  - URLキー - ハッシュでURLをルックアップするキー
  - '' - 最後の行を示す空のリテラル。合計や平均を表示したい場合に便利。

Article written by Laurent Destailleur.
Follow @awstats_project