From: manolamancha <> Date: Mon, 3 May 2010 17:44:45 +0000 (+0000) Subject: Added plugin development documentation X-Git-Tag: AWSTATS_7_0_BETA2~54 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2a096a9da00c16faeb0d4f9bf97073df8b579bef;p=thirdparty%2FAWStats.git Added plugin development documentation --- diff --git a/docs/awstats_dev_plugins.html b/docs/awstats_dev_plugins.html new file mode 100644 index 00000000..d9ef8a0a --- /dev/null +++ b/docs/awstats_dev_plugins.html @@ -0,0 +1,177 @@ + + + + + +AWStats Documentation - Plugins Development + + + + + + + + + + + + + + + +
+
+AWStats logfile analyzer 6.95 +Documentation
+
+		 +  +
+
+
+

Plugin +Development

+AWStats has a very flexible plugin architecture that is easy to use and +allows for powerful extensibility. Here is the information you need to +get started rolling your own. In this documentation, the terms +plugin and module will be used interchangeably.
+
+ +
+Plugin Files, +Location
+
AWStats plugins are implemented as Perl modules with a file +extension of .pm. Every time you run AWStats, either in update mode or +HTML output mode, the configuration file will be parsed for the names +of plugins to load. Then AWStats will scan the plugins folder for +matching modules and load them into memory, executing hooks at the +appropriate time during a run. Thus, when you create a plugin, you have +to store the file in the plugins directory under the folder where +awstats.pl resides.
+
+Hooks
+
In order to be useful, your plugin must implement +any number +of different "hooks" that will be called at various points during the +AWStats run. A hook is simply a Perl sub routine that will receive +various parameters, perform whatever actions you desire such as +calculations, modifications or output, and optionally return a value.
+Note: all +plugins MUST implement the Init_ +hook to initialize the module and determine if the plugin will run +under the current version of AWStats.
+For information on the available hooks, view the Hooks +document.
+
+Required +Variables
+
Each plugin must implement three required, local variables +including the name, hooks, implements and required AWStats Version. +Typically you implement these at the top of your plugin file as in this +example code:
+
+#-----------------------------------------------------------------------------
+# PLUGIN VARIABLES
+#-----------------------------------------------------------------------------
+# <-----
+# ENTER HERE THE MINIMUM AWSTATS VERSION REQUIRED BY YOUR PLUGIN
+# AND THE NAME OF ALL FUNCTIONS THE PLUGIN MANAGE.
+my $PluginNeedAWStatsVersion="5.5";
+my $PluginHooksFunctions="GetCountryCodeByAddr GetCountryCodeByName +ShowInfoHost";
+my $PluginName = "geoipfree";
+my $PluginImplements = "mou";
+# ----->
+
+The $PluginNeedAWStatsVersion +indicates the minimum version of AWStats that your plugin requires to +run properly. If a user attempts to implement your plugin with an older +version of the program, the plugin will not load.
+
+$PluginHooksFunctions +is a space delimited list of the different hooks that your plugin will +implement. This list should only include names defined in the hooks list. +You should not list any private module functions or +the Init_ +hook in this list. The naming convention for all hooks is HookName_PluginName. +The hooks like only includes the hook name without the underscore.
+
+$PluginName +is simply the name of your plugin, exactly as it appears in the hooks +and file name. This will be used by AWStats on load.
+
+$PluginImplements +is a list of letter codes mapped to operations that your plugin +performs. Without at least one of these letter codes, your plugin will +never run. The codes are:
+ +Accessible Variables
+
Your plugin has access to all of the global variables +declared at +the top of the AWStats.pl program. While you can write to these +variables, it's best to only read them as another plugin may make +unexpected modifications. However you can declare global variables +within your own plugin and share those across other plugins. Just +declare them inside the normal use +vars qw/ ... / block within your own module.
+
+Thus you can (and should) use settings from the configuration file and +determine the debug level.
+
+Accessible Functions
+
Plugins have access to all of the functions declared in the +main +AWStats.pl file. For debugging and error handling, you should use the debug and error functions. +Below are some common functions that plugins take advantage of +(remember you don't have to re-invent the wheel):
+
+debug("debug message", debug_level) +- Writes the "debug message" to the standard output if the (integer) +debug_level is lower or equal to that set by the user at runtime. The +higher the debug level, the less important or more informational the +message. After outputting the message, the program continues running.
+
+error("error message") +- Writes the "error message" to the standard output and halts program +execution.
+
+Format_Bytes(bytes) +- Converts the incoming decimal value to Kilobytes, Megabytes, +Gigabytes and so forth. So if you put in 1024.5 it will spit out "1 KB"
+
+Format_Date(YYYYMMDDHHMMSS) +- Converts the incoming timestamps to something like 30 Apr 2010 - 16:55
+
+Format_Number(number) - +Adds commas or a user defined character where appropriate to separate +numbers for easier reading.
+
+
+
+ \ No newline at end of file diff --git a/docs/awstats_dev_plugins_graphs.html b/docs/awstats_dev_plugins_graphs.html new file mode 100644 index 00000000..9663aa75 --- /dev/null +++ b/docs/awstats_dev_plugins_graphs.html @@ -0,0 +1,201 @@ + + + + + +AWStats Documentation - Plugins Development - Graphs + + + + + + + + + + + + + + + +
+
+AWStats logfile analyzer 6.95 +Documentation
+
+		 +  +
+
+
+

Plugin +Graphs

+Charts, graphs and maps can be generated by your plugin and make +AWStats reports look nice. AWStats generates arrays of values, label +names and titles so that your plugin only has to handle the final data +and display it as you wish.
+NOTE: Only +one graphing plugin should be choose by a user at any given time, thus +your plugin should generate as many graphs as possible. If more than +one graphing plugin is enabled at any given time, multiple graphs will +appear in the output for each graph type.
+
+Below is a list of variables passed to the graphin hook and how you +should use them.
+ +
+Title
+
This is simply the title of the graph as it should be +displayed to the end user. This could be "Hosts (Top 5)" or "Monthly +History" or anything else. Of course, you don't have to show the title +unless you want to.
+
+Type
+
The type is important as your graphing plugin should +determine what type of graph to output depending on the type AWStats is +requesting. For information on types and the data order, check the Types and Data section.
+ +Block Label
+
This is a label for each group of data, usually labels for +the X axis such as the days of the week, months of the year, etc. Your +plugin can use the scalar count of values in this array as the number +of times a loop needs to iterate through an axis. For example:
+
+foreach my $j (1.. (scalar +@$blocklabel)) { ... }
+
+Val Label
+
@vallabel contains a list of labels for each of the data sets +such as "pages", "hits", etc. Use the scalar count of values when +accessing the data matrix.
+
+Val Color
+
This is an array of color values associated with each type of +data as assigned by the configuration file or the defaults in AWStats. +Each color is a web formatted RGB hex encoded value such as "FFFFFF" or +"000000".
+
+Val Max
+
This array contains the maximum individual numeric value for +each of the types of data stored in the data array. The count is the +same as the the color array.
+
+Val Total
+
This array contains the total numeric value for each type of +data stored in the data array. The count is the same as the +the color array.
+
+Val Average
+
This array contains the average numeric value for each type +of data +stored in the data array. The count is the same as the the +color array.
+
+Val Data
+
This array contains the actual data values for each type of +data indexed by each data type for a block of data, then the next set +of types for a block and so on. Thus if we were looking at the monthly +graph, the data would be laid out thusly:
+
+$valdata[0] --> January Unique Visitors
+$valdata[1] --> January Number of Visits
+$valdata[2] --> January Pages
+$valdata[3] --> January Hits
+$valdata[4] --> January Bandwidth
+$valdata[5] --> February Unique Visitors
+$valdata[6] --> February Number of Visits
+....
+
+Graph Types and Data
+
Below is a list of the different graph types and the order in +which data appears in the associated arrays.
+
+ +
+
+ + \ No newline at end of file diff --git a/docs/awstats_dev_plugins_hooks.html b/docs/awstats_dev_plugins_hooks.html new file mode 100644 index 00000000..ac8a430b --- /dev/null +++ b/docs/awstats_dev_plugins_hooks.html @@ -0,0 +1,386 @@ + + + + + +AWStats Documentation - Plugins Development - Hooks + + + + + + + + + + + + + + + +
+
+AWStats logfile analyzer 6.95 +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
+
+
+
+ + \ No newline at end of file