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:
- 9380 Bytes
- Properties:
- Property svn:executable is set to *
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html><head> |
| 3 | <meta content="AWStats Documentation - Contrib and resource page" name="description"> |
| 4 | <meta content="awstats, awstat, log, file, analyzer, contrib, plugins, resources, maxmind, geoipfree, geoip, cities, regions, countries, frontend" name="keywords"> |
| 5 | <meta content="index,follow" name="robots"> |
| 6 | <meta content="AWStats Documentation - Plugins Development" name="title"><title>AWStats Documentation - Plugins Development</title> |
| 7 | |
| 8 | <link type="text/css" href="styles.css" rel="stylesheet"> |
| 9 | <link rel="stylesheet" type="text/css" href="scripts/prettify.css"> |
| 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 | Development</h1> |
| 34 | AWStats has a very flexible plugin architecture that is easy to use and |
| 35 | allows for powerful extensibility. Here is the information you need to |
| 36 | get started rolling your own. In this documentation, the terms |
| 37 | plugin and module will be used interchangeably. <br> |
| 38 | <br> |
| 39 | <ul> |
| 40 | <li><a href="#Plugin_Files_Location">Plugin Files, |
| 41 | Location</a></li> |
| 42 | <li><a href="#Hooks">Hooks</a></li> |
| 43 | <li><a href="#Required_Variables">Required |
| 44 | Variables</a></li> |
| 45 | <li><a href="#Accessible_Variables">Accessible |
| 46 | Variables</a></li> |
| 47 | <li><a href="#Accessible_Functions">Accessible |
| 48 | Functions</a></li> |
| 49 | <li><a href="awstats_dev_plugins_hooks.html">Available |
| 50 | Hooks</a></li> |
| 51 | </ul> |
| 52 | <br> |
| 53 | <a name="Plugin_Files_Location"></a><font color="#665544" size="3"><b>Plugin Files, |
| 54 | Location</b></font><br> |
| 55 | <hr>AWStats plugins are implemented as Perl modules with a file |
| 56 | extension of .pm. Every time you run AWStats, either in update mode or |
| 57 | HTML output mode, the configuration file will be parsed for the names |
| 58 | of plugins to load. Then AWStats will scan the plugins folder for |
| 59 | matching modules and load them into memory, executing hooks at the |
| 60 | appropriate time during a run. Thus, when you create a plugin, you have |
| 61 | to store the file in the plugins directory under the folder where |
| 62 | awstats.pl resides. <br> |
| 63 | <br> |
| 64 | <font color="#665544" size="3"><b><a name="Hooks"></a>Hooks</b></font><br> |
| 65 | <hr>In order to be useful, your plugin must implement |
| 66 | any number |
| 67 | of different "hooks" that will be called at various points during the |
| 68 | AWStats run. A hook is simply a Perl sub routine that will receive |
| 69 | various parameters, perform whatever actions you desire such as |
| 70 | calculations, modifications or output, and optionally return a value. <br> |
| 71 | <span style="font-weight: bold;">Note:</span> all |
| 72 | plugins MUST implement the <span style="font-style: italic;">Init_</span> |
| 73 | hook to initialize the module and determine if the plugin will run |
| 74 | under the current version of AWStats.<br> |
| 75 | For information on the available hooks, <a href="awstats_dev_plugins_hooks.html">view the Hooks |
| 76 | document.</a><br> |
| 77 | <a name="Required_Variables"></a><br> |
| 78 | <font color="#665544" size="3"><b>Required |
| 79 | Variables</b></font><br> |
| 80 | <hr>Each plugin must implement three required, local variables |
| 81 | including the name, hooks, implements and required AWStats Version. |
| 82 | Typically you implement these at the top of your plugin file as in this |
| 83 | example code:<br> |
| 84 | <br> |
| 85 | <code class="prettyprint">#-----------------------------------------------------------------------------<br> |
| 86 | # PLUGIN VARIABLES<br> |
| 87 | #-----------------------------------------------------------------------------<br> |
| 88 | # <-----<br> |
| 89 | # ENTER HERE THE MINIMUM AWSTATS VERSION REQUIRED BY YOUR PLUGIN<br> |
| 90 | # AND THE NAME OF ALL FUNCTIONS THE PLUGIN MANAGE.<br> |
| 91 | my $PluginNeedAWStatsVersion="5.5";<br> |
| 92 | my $PluginHooksFunctions="GetCountryCodeByAddr GetCountryCodeByName |
| 93 | ShowInfoHost";<br> |
| 94 | my $PluginName = "geoipfree";<br> |
| 95 | my $PluginImplements = "mou";<br> |
| 96 | # -----></code><br> |
| 97 | <br> |
| 98 | The <span style="font-weight: bold;">$PluginNeedAWStatsVersion</span> |
| 99 | indicates the minimum version of AWStats that your plugin requires to |
| 100 | run properly. If a user attempts to implement your plugin with an older |
| 101 | version of the program, the plugin will not load.<br> |
| 102 | <br> |
| 103 | <span style="font-weight: bold;">$PluginHooksFunctions</span> |
| 104 | is a space delimited list of the different hooks that your plugin will |
| 105 | implement. This list should only include names defined in the <a href="awstats_dev_plugins_hooks.html">hooks list</a>. |
| 106 | You should not list any private module functions or |
| 107 | the <span style="font-style: italic;">Init_</span> |
| 108 | hook in this list. The naming convention for all hooks is <span style="font-style: italic;">HookName_PluginName</span>. |
| 109 | The hooks like only includes the hook name without the underscore.<br> |
| 110 | <br> |
| 111 | <span style="font-weight: bold;">$PluginName</span> |
| 112 | is simply the name of your plugin, exactly as it appears in the hooks |
| 113 | and file name. This will be used by AWStats on load.<br> |
| 114 | <br> |
| 115 | <span style="font-weight: bold;">$PluginImplements</span> |
| 116 | is a list of letter codes mapped to operations that your plugin |
| 117 | performs. Without at least one of these letter codes, your plugin will |
| 118 | never run. The codes are:<br> |
| 119 | <ul> |
| 120 | <li>"m" - a Menu Handler plugin that |
| 121 | provides links to navigate around reports. The plugin will be called |
| 122 | any time a menu is displayed, such as in the left frame in cgi mode or |
| 123 | top navigation in static mode. </li> |
| 124 | <li>"o" - an Output plugin that will be loaded when AWStats is |
| 125 | generating a report via dynamic CGI or static HTML</li> |
| 126 | <li>"u" - an Update plugin that will process data and is run |
| 127 | when AWStats is parsing log files and updating the history data files.</li> |
| 128 | </ul> |
| 129 | <font color="#665544" size="3"><b><a name="Accessible_Variables"></a>Accessible Variables</b></font><br> |
| 130 | <hr>Your plugin has access to all of the global variables |
| 131 | declared at |
| 132 | the top of the AWStats.pl program. While you can write to these |
| 133 | variables, it's best to only read them as another plugin may make |
| 134 | unexpected modifications. However you can declare global variables |
| 135 | within your own plugin and share those across other plugins. Just |
| 136 | declare them inside the normal <span style="font-style: italic;">use |
| 137 | vars qw/ ... /</span> block within your own module.<br> |
| 138 | <br> |
| 139 | Thus you can (and should) use settings from the configuration file and |
| 140 | determine the debug level.<br> |
| 141 | <br> |
| 142 | <font color="#665544" size="3"><b><a name="Accessible_Functions"></a>Accessible Functions</b></font><br> |
| 143 | <hr>Plugins have access to all of the functions declared in the |
| 144 | main |
| 145 | AWStats.pl file. For debugging and error handling, you should use the <span style="font-style: italic;">debug</span> and <span style="font-style: italic;">error</span> functions. |
| 146 | Below are some common functions that plugins take advantage of |
| 147 | (remember you don't have to re-invent the wheel):<br> |
| 148 | <br> |
| 149 | <span style="font-weight: bold;">debug("<span style="font-style: italic;">debug message</span>", <span style="font-style: italic;">debug_level</span>)</span> |
| 150 | - Writes the "debug message" to the standard output if the (integer) |
| 151 | debug_level is lower or equal to that set by the user at runtime. The |
| 152 | higher the debug level, the less important or more informational the |
| 153 | message. After outputting the message, the program continues running.<br> |
| 154 | <br> |
| 155 | <span style="font-weight: bold;">error("<span style="font-style: italic;">error message</span>")</span> |
| 156 | - Writes the "error message" to the standard output and halts program |
| 157 | execution. <br> |
| 158 | <br> |
| 159 | <span style="font-weight: bold;">Format_Bytes(<span style="font-style: italic;">bytes</span>)</span> |
| 160 | - Converts the incoming decimal value to Kilobytes, Megabytes, |
| 161 | Gigabytes and so forth. So if you put in 1024.5 it will spit out "1 KB"<br> |
| 162 | <br> |
| 163 | <span style="font-weight: bold;">Format_Date(<span style="font-style: italic;">YYYYMMDDHHMMSS</span>)</span> |
| 164 | - Converts the incoming timestamps to something like 30 Apr 2010 - 16:55<br> |
| 165 | <br> |
| 166 | <span style="font-weight: bold;">Format_Number(<span style="font-style: italic;">number</span>) -</span> |
| 167 | Adds commas or a user defined character where appropriate to separate |
| 168 | numbers for easier reading.<br> |
| 169 | <br> |
| 170 | <hr> |
| 171 | <script language="javascript"> |
| 172 | var date='$Date: 2010/06/22 21:35:24 $'; |
| 173 | document.writeln("Last revision: "+date); |
| 174 | </script><!-- |
| 175 | First version of this tool was designed to analyze folowing web sites: |
| 176 | --><br> |
| 177 | </body></html> |
