← Back to branch summary

~ubuntu-branches/ubuntu/quantal/awstats/quantal

« back to all changes in this revision

Viewing changes to docs/awstats_dev_plugins.html

  • Committer: Bazaar Package Importer
  • Author(s): Jonas Smedegaard, Sergey B Kirpichev, Jonas Smedegaard
  • Date: 2011-03-12 19:44:25 UTC
  • mfrom: (1.2.8 upstream)
  • Revision ID: james.westby@ubuntu.com-20110312194425-hn7bo427pgqw2smz
Tags: 7.0~dfsg-1
http://bugs.debian.org/613447
http://bugs.debian.org/610632
* New upstream release.
  Closes: bug#613447.

[ Sergey B Kirpichev ]
* Unfuzz patches.
* Update patch 1008.
* Drop obsolete patches.
* Fix +x bit on *.js in docs/examples
* Avoid asterisks in debian/NEWS entries, to please lintian.
* Fix recode bulgarian tooltips file as utf-8.
  Closes: bug#610632.
* Forward patches 0007 and 1015 upstream.
* Allow DM (Debian Maintainer) uploads.

[ Jonas Smedegaard ]
* Update copyright file:
  + Rewrite using Subversion rev.173 of draft DEP5 format.
  + Add some previously missed authors and licenses.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/awstats_dev_plugins.html
 
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
&nbsp;
 
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&nbsp;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&nbsp;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
# &lt;-----<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
# -----&gt;</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&nbsp;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.&nbsp;</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>
 
 
b'\\ No newline at end of file'