AWStats logfile analyzer 7.5 Documentation

  


Plugin Hooks

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:

sub Init_mypluginname()

If you need a hook that isn't listed, please contact the developers through Source Forge and place a request.
Required Hooks
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:

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

If your plugin will accept a number of parameters, insert a line similar to the following:

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

Be sure to perform validation on the local variables and change the number of splits to the number of parameters you expect to read.

Common Hooks

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

Processing/Update Hooks

SectionWriteHistory_pluginname
Type: Update
Parameters: $xml,   $xmlbb, $xmlbs, $xmlbe, $xmlrb,  $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,  $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 and is useful for counting hits to the host or looking up additional information.

Output/HTML Hooks

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 information to the HTML header. Only print the individual style definitions, not the beginning or ending style tags (i.e. <style></style>)

AddHTMLHeader_pluginname
Type: Output
Parameters: None
Called: When HTML headers are printed, just before the closing </head> 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 </html> 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, $display, @blocklabel, @vallabel, @valcolor, @valmax, @valtotal, @valaverage, @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, see the graph plugin page

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


Article written by .

Follow @awstats_project