Changesets can be listed by changeset number.
The Git repository is here.
- Revision:
- 297
- Log:
Updated to AWStats 7.0.
- Author:
- rool
- Date:
- Fri Mar 18 13:33:29 +0000 2011
- Size:
- 19899 Bytes
- Properties:
- Property svn:executable is set to *
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html><head> |
| 3 | <meta name="description" content="AWStats Documentation - Contrib and resource page"> |
| 4 | <meta name="keywords" content="awstats, awstat, log, file, analyzer, contrib, plugins, resources, maxmind, geoipfree, geoip, cities, regions, countries, frontend"> |
| 5 | <meta name="robots" content="index,follow"> |
| 6 | <meta name="title" content="AWStats Documentation - Plugins Development - Hooks"><title>AWStats Documentation - Plugins Development - Hooks</title> |
| 7 | |
| 8 | <link rel="stylesheet" href="styles.css" type="text/css"> |
| 9 | <link href="scripts/prettify.css" type="text/css" rel="stylesheet"> |
| 10 | <script type="text/javascript" src="scripts/prettify.js"></script><!-- $Revision: 1.2 $ - $Author: eldy $ - $Date: 2010/06/22 21:35:24 $ --> |
| 11 | </head> |
| 12 | <body onload="prettyPrint()"> |
| 13 | <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%"> |
| 14 | <!-- Large --> |
| 15 | <tbody> |
| 16 | <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;"> |
| 17 | <td align="center" bgcolor="#9999cc"><a href="/"><img src="images/awstats_logo1.png" border="0"></a></td> |
| 18 | <td align="center" bgcolor="#9999cc"> |
| 19 | <br> |
| 20 | <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"><b>AWStats logfile analyzer 7.0 |
| 21 | Documentation</b></font><br> |
| 22 | <br> |
| 23 | </td> |
| 24 | <td align="center" bgcolor="#9999cc"> |
| 25 | |
| 26 | </td> |
| 27 | </tr> |
| 28 | </tbody> |
| 29 | </table> |
| 30 | <br> |
| 31 | <br> |
| 32 | <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 |
| 33 | Hooks</h1> |
| 34 | The following is a list of hooks available to plugin |
| 35 | developers. At various steps in the reporting or parsing process, |
| 36 | AWStats will scan the plugin list for any matching hooks and execute |
| 37 | them. All hooks start with the name of the hook, an underscore and then |
| 38 | the plugin name. So for example, if I was creating a plugin called |
| 39 | "mypluginname" then the initialization hook would look like:<br> |
| 40 | <br> |
| 41 | <code class="prettyprint">sub Init_mypluginname()</code><br> |
| 42 | <br> |
| 43 | If you need a hook that isn't listed, please contact the developers |
| 44 | through Source Forge and place a request.<br> |
| 45 | <ul> |
| 46 | <li><a href="#Required_Hooks">Required Hooks</a></li> |
| 47 | <li><a href="#Common_Hooks_">Common Hooks</a></li> |
| 48 | <li><a href="#ProcessingUpdate_Hooks">Processing/Update |
| 49 | Hooks</a></li> |
| 50 | <li><a href="#OutputHTML_Hooks_">Output/HTML Hooks</a><br> |
| 51 | </li> |
| 52 | </ul> |
| 53 | <font color="#665544" size="3"><b><a name="Required_Hooks"></a>Required Hooks</b></font><br> |
| 54 | <hr><span style="font-weight: bold;">Init_<span style="font-style: italic;">pluginname</span><br> |
| 55 | </span><span style="font-style: italic;">Type:</span> |
| 56 | All<span style="font-style: italic;"></span><br> |
| 57 | <span style="font-style: italic;">Parameters:</span> |
| 58 | Any parameters passed from the configuration file<br> |
| 59 | <span style="font-style: italic;">Called:</span> |
| 60 | After loading configuration file and parsing plugins. Before parsing or |
| 61 | HTML output<br> |
| 62 | <span style="font-style: italic;">Description:</span> |
| 63 | The initialization hook is used to load parameters from the |
| 64 | configuration file and initialize variables used in your plugin before |
| 65 | any other hooks are called. This is a good place to initialize any hash |
| 66 | tables you need or open data files. <br> |
| 67 | <span style="font-weight: bold;">Note:</span> <span style="font-style: italic;">Init_</span> must return a |
| 68 | list of hooks that your plugin implements in order for it to be used by |
| 69 | AWStats. For example:<br> |
| 70 | <br> |
| 71 | <code class="prettyprint">sub Init_geoip_region_maxmind {<br> |
| 72 | my |
| 73 | $checkversion=&Check_Plugin_Version($PluginNeedAWStatsVersion);<br> |
| 74 | return ($checkversion?$checkversion:"$PluginHooksFunctions");<br> |
| 75 | }</code><br> |
| 76 | <br> |
| 77 | If your plugin will accept a number of parameters, insert a line |
| 78 | similar to the following:<br> |
| 79 | <br> |
| 80 | <code class="prettyprint">my $InitParams=shift;<br> |
| 81 | my ($mode,$datafile,$override)=split(/\s+/,$InitParams,3);</code><br> |
| 82 | <br> |
| 83 | Be sure to perform validation on the local variables and change the |
| 84 | number of splits to the number of parameters you expect to read.<span style="font-weight: bold;"><br> |
| 85 | </span> |
| 86 | <h2><a name="Common_Hooks_"></a><font color="#665544" size="3"><b><a name="Common_Hooks"></a>Common Hooks</b></font><br> |
| 87 | </h2> |
| 88 | <hr><span style="font-weight: bold;">SectionInitHashArray_<span style="font-style: italic;">pluginname</span><br> |
| 89 | </span><span style="font-style: italic;">Type:</span> |
| 90 | All<span style="font-style: italic;"></span><br> |
| 91 | <span style="font-style: italic;">Parameters:</span> |
| 92 | None<br> |
| 93 | <span style="font-style: italic;">Called:</span> |
| 94 | When AWStats InitHash is called, such as at startup, when purging a |
| 95 | history file or when a new month begins during processing.<br> |
| 96 | <span style="font-style: italic;">Description:</span> |
| 97 | Use to initialize or clear any hash variables local to your plugin<br> |
| 98 | <h2><font color="#665544" size="3"><b><a name="ProcessingUpdate_Hooks"></a>Processing/Update |
| 99 | Hooks</b></font><br> |
| 100 | </h2> |
| 101 | <hr><span style="font-weight: bold;"></span><span style="font-weight: bold;">SectionWriteHistory_<span style="font-style: italic;">pluginname</span><br> |
| 102 | </span><span style="font-style: italic;">Type:</span> |
| 103 | Update<span style="font-style: italic;"></span><br> |
| 104 | <span style="font-style: italic;">Parameters:</span> |
| 105 | $xml, $xmlbb, $xmlbs, $xmlbe, $xmlrb, |
| 106 | $xmlrs, $xmlre, $xmleb, $xmlee<br> |
| 107 | <span style="font-style: italic;">Called:</span> |
| 108 | Whenever the history file is written in AWStats<br> |
| 109 | <span style="font-style: italic;">Description:</span> |
| 110 | Lets your plugin |
| 111 | write a section to the history file. Please note that if your plugin |
| 112 | stores a lot of data, it could greatly increase the history file size |
| 113 | and slow down loading and processing. In such a situation, you may want |
| 114 | to use this as a trigger to write to a separate history file and use |
| 115 | the <span style="font-style: italic;">SectionReadHistory_</span> |
| 116 | hook as a trigger to read that data.<br> |
| 117 | XML parameters are the pre-defined XML tags the history file is using<br> |
| 118 | <br> |
| 119 | <span style="font-weight: bold;">SectionReadHistory_<span style="font-style: italic;">pluginname</span><br> |
| 120 | </span><span style="font-style: italic;">Type:</span> |
| 121 | Update, Output<span style="font-style: italic;"></span><br> |
| 122 | <span style="font-style: italic;">Parameters:</span> |
| 123 | $issectiontoload, $readxml, $xmleb, $countlines<br> |
| 124 | <span style="font-style: italic;">Called:</span> |
| 125 | Whenever the history file is loaded in AWStats<br> |
| 126 | <span style="font-style: italic;">Description:</span> |
| 127 | Lets your plugin read a section that it had written to the history |
| 128 | file. The history log is always loaded before parsing log entries and |
| 129 | before outputing HTML. <br> |
| 130 | $issectiontoload - the name of the plugin section found in the history |
| 131 | file. If this is true, then the plugin should process the field data<br> |
| 132 | $readxml - True if the history file is in XML format<br> |
| 133 | $xmleb - XML element opening tag<br> |
| 134 | $countlines - how many lines have been read from the history file so far<br> |
| 135 | <span style="font-weight: bold;"><br> |
| 136 | SectionProcessHostname_<span style="font-style: italic;">pluginname</span><br> |
| 137 | </span><span style="font-style: italic;">Type:</span> |
| 138 | Update<br> |
| 139 | <span style="font-style: italic;">Required:</span> No<br> |
| 140 | <span style="font-style: italic;">Parameters:</span> |
| 141 | Resolved hostname<br> |
| 142 | <span style="font-style: italic;">Called:</span> On |
| 143 | each line of a log file IF the hostname was resolved<br> |
| 144 | <span style="font-style: italic;">Description:</span> |
| 145 | Processes a resolved host name, i.e. <span style="font-style: italic;">www.google.com</span> and |
| 146 | is useful for counting hits to the host or looking up additional |
| 147 | information.<br> |
| 148 | <br> |
| 149 | <span style="font-weight: bold;">SectionProcessIP_<span style="font-style: italic;">pluginname</span><br> |
| 150 | </span><span style="font-style: italic;">Type:</span> |
| 151 | Update<span style="font-style: italic;"></span><br> |
| 152 | <span style="font-style: italic;">Parameters:</span> |
| 153 | $Host<br> |
| 154 | <span style="font-style: italic;">Called:</span> On |
| 155 | each line of a log file IF DNS resolution is turned off or a host was |
| 156 | not resolved<br> |
| 157 | <span style="font-style: italic;">Description:</span> |
| 158 | Processes an IP address i.e. <span style="font-style: italic;">192.168.1.1 </span>and |
| 159 | is useful for counting hits to the host or looking up additional |
| 160 | information.<br> |
| 161 | <h2><a name="OutputHTML_Hooks_"></a><font color="#665544" size="3"><b><a name="OutputHTML_Hooks"></a>Output/HTML Hooks</b></font><br> |
| 162 | </h2> |
| 163 | <hr><span style="font-weight: bold;">AddHTMLMenuLink_<span style="font-style: italic;">pluginname</span><br> |
| 164 | </span><span style="font-style: italic;">Type:</span> |
| 165 | Output<span style="font-style: italic;"></span><br> |
| 166 | <span style="font-style: italic;">Parameters:</span> |
| 167 | $categ, $menu, $menulink, $menutext<br> |
| 168 | <span style="font-style: italic;">Called:</span> |
| 169 | Each time a new menu category is printed in the navigation frame or |
| 170 | section<br> |
| 171 | <span style="font-style: italic;">Description:</span> |
| 172 | Inserts a menu item into the navigation area that will link back to the |
| 173 | <span style="font-style: italic;">AddHTMLGraph_</span> |
| 174 | hook defined in your plugin. If that hook is undefined, the user will |
| 175 | experience an error. Requires <span style="font-style: italic;">AddHTMLGraph_</span> |
| 176 | hook<br> |
| 177 | <span class="highlighted">$categ</span> - name of |
| 178 | the main navigation category such as 'who' or 'hosts'<br> |
| 179 | $menu - passback where you assign the position your link should appear |
| 180 | in the menu<br> |
| 181 | $menulink - passback declaring the type of link<br> |
| 182 | $menutext - passback of the text to be displayed to the user<br> |
| 183 | <br> |
| 184 | <span style="font-weight: bold;">AddHTMLGraph_<span style="font-style: italic;">pluginname</span><br> |
| 185 | </span><span style="font-style: italic;">Type:</span> |
| 186 | Output<span style="font-style: italic;"></span><br> |
| 187 | <span style="font-style: italic;">Parameters:</span>None<br> |
| 188 | <span style="font-style: italic;">Called:</span> |
| 189 | When the <span style="font-style: italic;">AddHTMLMenuLink_</span> |
| 190 | created link is clicked, after HTML headers are sent and before HTML |
| 191 | footers are sent<br> |
| 192 | <span style="font-style: italic;">Description:</span> |
| 193 | Used to generate a dedicated report page with information specific to |
| 194 | your plugin such as the Hosts report or Regions page. You are only |
| 195 | responsible for the HTML between the standard AWStats header and footer.<span style="font-weight: bold;"></span><br> |
| 196 | <br> |
| 197 | <span style="font-weight: bold;">AddHTMLStyles_pluginname<br> |
| 198 | </span><span style="font-style: italic;">Type:</span> |
| 199 | Output<span style="font-style: italic;"></span><br> |
| 200 | <span style="font-style: italic;">Parameters:</span> |
| 201 | None<br> |
| 202 | <span style="font-style: italic;">Called:</span> |
| 203 | Whenever HTML headers are printed IF the configuration file does not |
| 204 | define a specific style sheet URL.<br> |
| 205 | <span style="font-style: italic;">Description:</span> |
| 206 | Use this section to output style information to the HTML |
| 207 | header. Only print the individual style definitions, not the beginning |
| 208 | or ending style tags (i.e. <span style="font-style: italic;"><style></style>)</span><br> |
| 209 | <br> |
| 210 | <span style="font-weight: bold;">AddHTMLHeader_pluginname<br> |
| 211 | </span><span style="font-style: italic;">Type:</span> |
| 212 | Output<span style="font-style: italic;"></span><br> |
| 213 | <span style="font-style: italic;">Parameters:</span> |
| 214 | None<br> |
| 215 | <span style="font-style: italic;">Called:</span> |
| 216 | When HTML headers are printed, just before the closing <span style="font-style: italic;"></head></span> |
| 217 | tag<br> |
| 218 | <span style="font-style: italic;">Description:</span> |
| 219 | If your plugin requires extra HTML header information such as java |
| 220 | script includes or meta tags, print them within this hook.<br> |
| 221 | <br> |
| 222 | <span style="font-weight: bold;">AddHTMLFooter_pluginname<br> |
| 223 | </span><span style="font-style: italic;">Type:</span> |
| 224 | Output<span style="font-style: italic;"></span><br> |
| 225 | <span style="font-style: italic;">Parameters:</span> |
| 226 | None<br> |
| 227 | <span style="font-style: italic;">Called:</span> |
| 228 | When HTML footers are printed<br> |
| 229 | <span style="font-style: italic;">Description:</span> |
| 230 | Prints footer HTML code before the AWStats copyright and closing <span style="font-style: italic;"></html></span> |
| 231 | tag. Useful if you need to output tracking code or banner ads<br> |
| 232 | <br> |
| 233 | <span style="font-weight: bold;">AddHTMLBodyHeader_<span style="font-style: italic;">pluginname</span><br> |
| 234 | </span><span style="font-style: italic;">Type:</span> |
| 235 | Output<span style="font-style: italic;"></span><br> |
| 236 | <span style="font-style: italic;">Parameters:</span> |
| 237 | None<br> |
| 238 | <span style="font-style: italic;">Called:</span> |
| 239 | After the HTML header is printed<br> |
| 240 | <span style="font-style: italic;">Description: </span>Used |
| 241 | to print information to the main HTML body before the banner or any |
| 242 | other information is printed<br> |
| 243 | <br> |
| 244 | <span style="font-weight: bold;">AddHTMLMenuHeader_<span style="font-style: italic;">pluginname</span><br> |
| 245 | </span><span style="font-style: italic;">Type:</span> |
| 246 | Output<span style="font-style: italic;"></span><br> |
| 247 | <span style="font-style: italic;">Parameters:</span> |
| 248 | None<br> |
| 249 | <span style="font-style: italic;">Called:</span> |
| 250 | After the HTML header and HTML body header<br> |
| 251 | <span style="font-style: italic;">Description: </span>Used |
| 252 | to print a header for the navigation menu whether it's inline on the |
| 253 | page or in the navigation frame.<br> |
| 254 | <br> |
| 255 | <span style="font-weight: bold;">AddHTMLMenuFooter_<span style="font-style: italic;">pluginname</span><br> |
| 256 | </span><span style="font-style: italic;">Type:</span> |
| 257 | Output<span style="font-style: italic;"></span><br> |
| 258 | <span style="font-style: italic;">Parameters:</span> |
| 259 | None<br> |
| 260 | <span style="font-style: italic;">Called:</span> |
| 261 | After the HTML navigation menu is printed<br> |
| 262 | <span style="font-style: italic;">Description: </span>Used |
| 263 | to print a footer for the navigation menu whether it's inline on the |
| 264 | page or in the navigation frame.<br> |
| 265 | <br> |
| 266 | <span style="font-weight: bold;">AddHTMLContentHeader_<span style="font-style: italic;">pluginname</span><br> |
| 267 | </span><span style="font-style: italic;">Type:</span> |
| 268 | Output<span style="font-style: italic;"></span><br> |
| 269 | <span style="font-style: italic;">Parameters:</span> |
| 270 | None<br> |
| 271 | <span style="font-style: italic;">Called:</span> |
| 272 | After the HTML navigation menu is printed<br> |
| 273 | <span style="font-style: italic;">Description: </span>Outputs |
| 274 | after the navigation menu but before any of the content tables in the |
| 275 | report pages. <br> |
| 276 | <br> |
| 277 | <span style="font-weight: bold;">TabHeadHTML_pluginname<br> |
| 278 | </span><span style="font-style: italic;">Type:</span> |
| 279 | Output<span style="font-style: italic;"></span><br> |
| 280 | <span style="font-style: italic;">Parameters:</span> |
| 281 | $title<br> |
| 282 | <span style="font-style: italic;">Called:</span> |
| 283 | When a new content table is beggining<br> |
| 284 | <span style="font-style: italic;">Description:</span> |
| 285 | Lets your plugin override the default table header style. Generally not |
| 286 | used.<br> |
| 287 | $title - title to display to the user<br> |
| 288 | <br> |
| 289 | <span style="font-weight: bold;">ShowInfoHost_<span style="font-style: italic;">pluginname</span><br> |
| 290 | </span><span style="font-style: italic;">Type:</span> |
| 291 | Output<span style="font-style: italic;"></span><br> |
| 292 | <span style="font-style: italic;">Parameters:</span> |
| 293 | $host<br> |
| 294 | <span style="font-style: italic;">Called:</span> |
| 295 | Each time a new host row is displayed, such as the main page host |
| 296 | section or the full host list page.<br> |
| 297 | <span style="font-style: italic;">Description:</span> |
| 298 | Used to display a table column with detailed information about the |
| 299 | host. The incoming parameter can be one of three values:<br> |
| 300 | '__title__' - literal value that indicates we're printing a column |
| 301 | header<br> |
| 302 | $Resolved Hostname - name of the host<br> |
| 303 | $IP Address - an unresolved dotted decimal IP<br> |
| 304 | <br> |
| 305 | <span style="font-weight: bold;">ShowInfoUser_<span style="font-style: italic;">pluginname</span><br> |
| 306 | </span><span style="font-style: italic;">Type:</span> |
| 307 | Output<span style="font-style: italic;"></span><br> |
| 308 | <span style="font-style: italic;">Parameters:</span> |
| 309 | $user<br> |
| 310 | <span style="font-style: italic;">Called:</span> |
| 311 | Each time a new authenticated user row is displayed<br> |
| 312 | <span style="font-style: italic;">Description:</span> |
| 313 | Used to display a table column with detailed information about the |
| 314 | user. The incoming parameter can have one of two values: <br> |
| 315 | '__title__' - literal value that indicates we're printing a column |
| 316 | header<br> |
| 317 | <span style="font-style: italic;">$user </span>- |
| 318 | the authenticated user name<br> |
| 319 | <br> |
| 320 | <span style="font-weight: bold;">ShowInfoCluster_<span style="font-style: italic;">pluginname</span><br> |
| 321 | </span><span style="font-style: italic;">Type:</span> |
| 322 | Output<span style="font-style: italic;"></span><br> |
| 323 | <span style="font-style: italic;">Parameters:</span> |
| 324 | $cluster<br> |
| 325 | <span style="font-style: italic;">Called:</span> |
| 326 | Each time a new cluster row is displayed<br> |
| 327 | <span style="font-style: italic;">Description:</span> |
| 328 | Used to display a table column with cluster information. The incoming |
| 329 | parameter can have one of two values: <br> |
| 330 | '__title__' - literal value that indicates we're printing a column |
| 331 | header<br> |
| 332 | $cluster - the cluster name<br> |
| 333 | <br> |
| 334 | <span style="font-weight: bold;">ShowInfoURL_<span style="font-style: italic;">pluginname</span><br> |
| 335 | </span><span style="font-style: italic;">Type:</span> |
| 336 | Output<span style="font-style: italic;"></span><br> |
| 337 | <span style="font-style: italic;">Parameters:</span> |
| 338 | $url<br> |
| 339 | <span style="font-style: italic;">Called:</span> |
| 340 | Each time a new page URL or referrer URL row is displayed<br> |
| 341 | <span style="font-style: italic;">Description:</span> |
| 342 | Used to display a table column with additional url information. The |
| 343 | incoming parameter can have one of two values: <br> |
| 344 | '__title__' - literal value that indicates we're printing a column |
| 345 | header<br> |
| 346 | url - the page or referrer URL<br> |
| 347 | <br> |
| 348 | <span style="font-weight: bold;">ShowInfoGraph_<span style="font-style: italic;">pluginname</span><br> |
| 349 | </span><span style="font-style: italic;">Type:</span> |
| 350 | Output<span style="font-style: italic;"></span><br> |
| 351 | <span style="font-style: italic;">Parameters: </span>$title, |
| 352 | $type, $display, @blocklabel, @vallabel, @valcolor, @valmax, @valtotal, @valaverage, @valdata<br> |
| 353 | <span style="font-style: italic;">Called:</span> Any |
| 354 | time a graph, chart or map is output to HTML<br> |
| 355 | <span style="font-style: italic;">Description:</span> |
| 356 | Used to display charts or graphs. AWstats will generate arrays of data, |
| 357 | colors and labels that your graphing plugin should be able to handle. |
| 358 | For more information, <a href="awstats_dev_plugins_graphs.html">see |
| 359 | the graph plugin page</a><br> |
| 360 | <br> |
| 361 | <span style="font-weight: bold;">ShowPagesAddField_<span style="font-style: italic;">pluginname</span><br> |
| 362 | </span><span style="font-style: italic;">Type:</span> |
| 363 | Output<span style="font-style: italic;"></span><br> |
| 364 | <span style="font-style: italic;">Parameters:</span> |
| 365 | $key<br> |
| 366 | <span style="font-style: italic;">Called:</span> |
| 367 | Each time a new page URL row is displayed on detailed URL pages and |
| 368 | main summary<br> |
| 369 | <span style="font-style: italic;">Description:</span> |
| 370 | Used to display a table column with additional url information. The |
| 371 | incoming parameter can have one of three values: <br> |
| 372 | 'title' - literal value that indicates we're printing a column header<br> |
| 373 | <span style="font-weight: bold;"></span>$key - URL |
| 374 | key to lookup in your hash<br> |
| 375 | '' - empty literal indicated the final row. Useful if you want to show |
| 376 | total or averages<br> |
| 377 | <br> |
| 378 | <br> |
| 379 | <hr> |
| 380 | <script language="javascript"> |
| 381 | var date='$Date: 2010/06/22 21:35:24 $'; |
| 382 | document.writeln("Last revision: "+date); |
| 383 | </script><!-- |
| 384 | First version of this tool was designed to analyze folowing web sites: |
| 385 | --> |
| 386 | </body></html> |
