One Hat Cyber Team

Edit File: awstats_dev_plugins_hooks.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head>
<meta name="description" content="AWStats Documentation about plugins development - Hooks">
<meta name="keywords" content="awstats, awstat, log, file, analyzer, contrib, plugins, hooks, resources, maxmind, geoipfree, geoip, cities, regions, countries, frontend">
<meta name="robots" content="index,follow">
<meta name="title" content="AWStats Documentation - Plugins Development - Hooks">
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>AWStats Documentation - Plugins Development - Hooks</title>
<link rel="stylesheet" href="styles.css" type="text/css">
<link href="https://plus.google.com/+LaurentDestailleur-Open-Source-Expert" rel="publisher" />
</head>

<body onload="prettyPrint()">
<table style="font-family: arial,helvetica,verdana; font-style: normal; font-variant: normal; font-weight: normal; font-size: 10pt; line-height: normal; font-size-adjust: none; font-stretch: normal;" bgcolor="#ffffff" border="0" cellpadding="0" cellspacing="0" width="100%">

<tbody>
<tr style="font-family: arial,helvetica,verdana; font-style: normal; font-variant: normal; font-weight: normal; font-size: 10pt; line-height: normal; font-size-adjust: none; font-stretch: normal;">
<td align="center" bgcolor="#9999cc"><a href="/"><img src="images/awstats_logo1.png" border="0"></a></td>
<td align="center" bgcolor="#9999cc">
 
<font style="font-family: arial,helvetica,sans-serif; font-style: normal; font-variant: normal; font-weight: normal; font-size: 16pt; line-height: normal; font-size-adjust: none; font-stretch: normal;" color="#eeeeff">AWStats logfile analyzer 7.5 Documentation 
 
</td>
<td align="center" bgcolor="#9999cc">
&nbsp;
</td>
</tr>
</tbody>
</table>
 
 
<h1 style="font-family: arial,helvetica,sanserif; font-style: normal; font-variant: normal; font-weight: normal; font-size: 26px; line-height: normal; font-size-adjust: none; font-stretch: normal;">Plugin
Hooks</h1>
The following is a list of hooks available to plugin
developers. At various steps in the reporting or parsing process,
AWStats will scan the plugin list for any matching hooks and execute
them. All hooks start with the name of the hook, an underscore and then
the plugin name. So for example, if I was creating a plugin called
"mypluginname" then the initialization hook would look like: 
 
<code class="prettyprint">sub Init_mypluginname()</code> 
 
If you need a hook that isn't listed, please contact the developers
through Source Forge and place a request. 
<ul>
<li><a href="#Required_Hooks">Required Hooks</a></li>
<li><a href="#Common_Hooks_">Common Hooks</a></li>
<li><a href="#ProcessingUpdate_Hooks">Processing/Update
Hooks</a></li>
<li><a href="#OutputHTML_Hooks_">Output/HTML Hooks</a> 
</li>
</ul>
<a name="Required_Hooks"></a>Required Hooks 
<hr>Init_pluginname 
Type:
All 
Parameters:
Any parameters passed from the configuration file 
Called:
After loading configuration file and parsing plugins. Before parsing or
HTML output 
Description:
The initialization hook is used to load parameters from the
configuration file and initialize variables used in your plugin before
any other hooks are called. This is a good place to initialize any hash
tables you need or open data files. 
Note: Init_ must return a
list of hooks that your plugin implements in order for it to be used by
AWStats. For example: 
 
<code class="prettyprint">sub Init_geoip_region_maxmind { 
my
$checkversion=&amp;Check_Plugin_Version($PluginNeedAWStatsVersion); 
return ($checkversion?$checkversion:"$PluginHooksFunctions"); 
}</code> 
 
If your plugin will accept a number of parameters, insert a line
similar to the following: 
 
<code class="prettyprint">my $InitParams=shift; 
my ($mode,$datafile,$override)=split(/\s+/,$InitParams,3);</code> 
 
Be sure to perform validation on the local variables and change the
number of splits to the number of parameters you expect to read. 

<h2><a name="Common_Hooks_"></a><a name="Common_Hooks"></a>Common Hooks 
</h2>
<hr>SectionInitHashArray_pluginname 
Type:
All 
Parameters:
None 
Called:
When AWStats InitHash is called, such as at startup, when purging a
history file or when a new month begins during processing. 
Description:
Use to initialize or clear any hash variables local to your plugin 
<h2><a name="ProcessingUpdate_Hooks"></a>Processing/Update
Hooks 
</h2>
<hr>SectionWriteHistory_pluginname 
Type:
Update 
Parameters:
$xml,&nbsp;&nbsp; $xmlbb, $xmlbs, $xmlbe, $xmlrb,&nbsp;
$xmlrs, $xmlre, $xmleb, $xmlee 
Called:
Whenever the history file is written in AWStats 
Description:
Lets your plugin
write a section to the history file. Please note that if your plugin
stores a lot of data, it could greatly increase the history file size
and slow down loading and processing. In such a situation, you may want
to use this as a trigger to write to a separate history file and use
the SectionReadHistory_
hook as a trigger to read that data. 
XML parameters are the pre-defined XML tags the history file is using 
 
SectionReadHistory_pluginname 
Type:
Update, Output 
Parameters:
$issectiontoload, $readxml, $xmleb,&nbsp; $countlines 
Called:
Whenever the history file is loaded in AWStats 
Description:
Lets your plugin read a section that it had written to the history
file. The history log is always loaded before parsing log entries and
before outputing HTML. 
$issectiontoload - the name of the plugin section found in the history
file. If this is true, then the plugin should process the field data 
$readxml - True if the history file is in XML format 
$xmleb - XML element opening tag 
$countlines - how many lines have been read from the history file so far 
 
SectionProcessHostname_pluginname 
Type:
Update 
Required: No 
Parameters:
Resolved hostname 
Called: On
each line of a log file IF the hostname was resolved 
Description:
Processes a resolved host name, i.e. www.google.com and
is useful for counting hits to the host or looking up additional
information. 
 
SectionProcessIP_pluginname 
Type:
Update 
Parameters:
$Host 
Called: On
each line of a log file IF DNS resolution is turned off or a host was
not resolved 
Description:
Processes an IP address i.e. 192.168.1.1&nbsp;and
is useful for counting hits to the host or looking up additional
information. 
<h2><a name="OutputHTML_Hooks_"></a><a name="OutputHTML_Hooks"></a>Output/HTML Hooks 
</h2>
<hr>AddHTMLMenuLink_pluginname 
Type:
Output 
Parameters:
$categ, $menu, $menulink, $menutext 
Called:
Each time a new menu category is printed in the navigation frame or
section 
Description:
Inserts a menu item into the navigation area that will link back to the
AddHTMLGraph_
hook defined in your plugin. If that hook is undefined, the user will
experience an error. Requires AddHTMLGraph_
hook 
$categ - name of
the main navigation category such as 'who' or 'hosts' 
$menu - passback where you assign the position your link should appear
in the menu 
$menulink - passback declaring the type of link 
$menutext - passback of the text to be displayed to the user 
 
AddHTMLGraph_pluginname 
Type:
Output 
Parameters:None 
Called:
When the AddHTMLMenuLink_
created link is clicked, after HTML headers are sent and before HTML
footers are sent 
Description:
Used to generate a dedicated report page with information specific to
your plugin such as the Hosts report or Regions page. You are only
responsible for the HTML between the standard AWStats header and footer. 
 
AddHTMLStyles_pluginname 
Type:
Output 
Parameters:
None 
Called:
Whenever HTML headers are printed IF the configuration file does not
define a specific style sheet URL. 
Description:
Use this section to output style&nbsp;information to the HTML
header. Only print the individual style definitions, not the beginning
or ending style tags (i.e. &lt;style&gt;&lt;/style&gt;) 
 
AddHTMLHeader_pluginname 
Type:
Output 
Parameters:
None 
Called:
When HTML headers are printed, just before the closing &lt;/head&gt;
tag 
Description:
If your plugin requires extra HTML header information such as java
script includes or meta tags, print them within this hook. 
 
AddHTMLFooter_pluginname 
Type:
Output 
Parameters:
None 
Called:
When HTML footers are printed 
Description:
Prints footer HTML code before the AWStats copyright and closing &lt;/html&gt;
tag. Useful if you need to output tracking code or banner ads 
 
AddHTMLBodyHeader_pluginname 
Type:
Output 
Parameters:
None 
Called:
After the HTML header is printed 
Description: Used
to print information to the main HTML body before the banner or any
other information is printed 
 
AddHTMLMenuHeader_pluginname 
Type:
Output 
Parameters:
None 
Called:
After the HTML header and HTML body header 
Description: Used
to print a header for the navigation menu whether it's inline on the
page or in the navigation frame. 
 
AddHTMLMenuFooter_pluginname 
Type:
Output 
Parameters:
None 
Called:
After the HTML navigation menu is printed 
Description: Used
to print a footer for the navigation menu whether it's inline on the
page or in the navigation frame. 
 
AddHTMLContentHeader_pluginname 
Type:
Output 
Parameters:
None 
Called:
After the HTML navigation menu is printed 
Description: Outputs
after the navigation menu but before any of the content tables in the
report pages. 
 
TabHeadHTML_pluginname 
Type:
Output 
Parameters:
$title 
Called:
When a new content table is beggining 
Description:
Lets your plugin override the default table header style. Generally not
used. 
$title - title to display to the user 
 
ShowInfoHost_pluginname 
Type:
Output 
Parameters:
$host 
Called:
Each time a new host row is displayed, such as the main page host
section or the full host list page. 
Description:
Used to display a table column with detailed information about the
host. The incoming parameter can be one of three values: 
'__title__' - literal value that indicates we're printing a column
header 
$Resolved Hostname - name of the host 
$IP Address - an unresolved dotted decimal IP 
 
ShowInfoUser_pluginname 
Type:
Output 
Parameters:
$user 
Called:
Each time a new authenticated user row is displayed 
Description:
Used to display a table column with detailed information about the
user. The incoming parameter can have one of two values: 
'__title__' - literal value that indicates we're printing a column
header 
$user -
the authenticated user name 
 
ShowInfoCluster_pluginname 
Type:
Output 
Parameters:
$cluster 
Called:
Each time a new cluster row is displayed 
Description:
Used to display a table column with cluster information. The incoming
parameter can have one of two values: 
'__title__' - literal value that indicates we're printing a column
header 
$cluster - the cluster name 
 
ShowInfoURL_pluginname 
Type:
Output 
Parameters:
$url 
Called:
Each time a new page URL or referrer URL row is displayed 
Description:
Used to display a table column with additional url information. The
incoming parameter can have one of two values: 
'__title__' - literal value that indicates we're printing a column
header 
url - the page or referrer URL 
 
ShowInfoGraph_pluginname 
Type:
Output 
Parameters: $title,
$type,&nbsp;$display,&nbsp;@blocklabel,&nbsp;@vallabel,&nbsp;@valcolor,&nbsp;@valmax,&nbsp;@valtotal,&nbsp;@valaverage,&nbsp;@valdata 
Called: Any
time a graph, chart or map is output to HTML 
Description:
Used to display charts or graphs. AWstats will generate arrays of data,
colors and labels that your graphing plugin should be able to handle.
For more information, <a href="awstats_dev_plugins_graphs.html">see
the graph plugin page</a> 
 
ShowPagesAddField_pluginname 
Type:
Output 
Parameters:
$key 
Called:
Each time a new page URL row is displayed on detailed URL pages and
main summary 
Description:
Used to display a table column with additional url information. The
incoming parameter can have one of three values: 
'title' - literal value that indicates we're printing a column header 
$key - URL
key to lookup in your hash 
'' - empty literal indicated the final row. Useful if you want to show
total or averages 
 
 
<hr>

<div class="htmldoc-ignore">

Article written by <a href="https://plus.google.com/+LaurentDestailleur-Open-Source-Expert?rel=author" rel="author" style="color: #ccc; font-weight: normal;">Laurent Destailleur</a>. 
 

<a href="https://twitter.com/awstats_project" class="twitter-follow-button" data-show-count="false">Follow @awstats_project</a>
</div>

</body></html>