<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
<document>
<header>
<title>Referer plugin</title>
</header>
<body>
<section>
<title>description</title>
<p></p>
<p>
The referer plugin simply logs to a user defined file all of the HTTP referer headers it
comes across. This is often useful if you want to see what google searches lead to your
site. It will also group referers by flavor with overall flavor totals and filtered by
date. This plugin will also filter referer's based on the contents of the blojsom wide
blacklist filter.
</p>
</section>
<section>
<title>installation and setup</title>
<p>
In your global
<code>plugin.properties</code> file, add the following line:
</p>
<source>
referer-log=org.blojsom.plugin.referer.RefererLogPlugin
</source>
<p>
You may then add "referer-log" to one of the flavor-based plugin chains.
These plugin chains can be found in the individual user's
<code>plugin.properties</code> file. For example:
</p>
<source>
html.blojsom-plugin-chain=referer-log
</source>
<p>
The referer plugin has its own configuration file,
<em>referer.properties</em>, that is
referenced in
<em>web.xml</em>.
</p>
<source>
<init-param>
<param-name>plugin-referer</param-name>
<param-value>referer.properties</param-value>
</init-param>
</source>
<p>
The
<em>referer.properties</em> file will be located in the respective
<code>/WEB-INF/(user-id)</code> directory and contains three configurable parameters:
</p>
<source>
#
# blojsom referer plugin configuration file
#
referer-display-size=40
referer-filename=/change/me/please/blojsom-referer.log
# NOTE:hit-count flavors just captures totals and not referer urls
hit-count-flavors=rss
</source>
<p>
<em>referer-display-size</em> controls the display size of the referer URL
<br/>
<em>referer-filename</em> is the location and filename of the log file it should write to on
shutdown of your application server
<br/>
<em>hit-count-flavors</em> is a comma-separated list of the flavors that the plugin should
track for referers. Flavors added to this list will only have their hit counts tracked,
but will not have the referer URL tracked
</p>
</section>
<section>
<title>filtering</title>
<p>
This plugin will use the contents of the blacklist filter to ignore referer's that match any of the filters.
this helps ignore those spam referers. This is automatic and no configuration, other that editing the
<em>blacklist.filters</em> file.
</p>
</section>
<section>
<title>context attributes and types</title>
<p>
The following table describes the context attributes that are available and their associated type.
</p>
<table>
<tr>
<th>Context key</th>
<th>Input or Output</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>REFERER_HISTORY</td>
<td>Output</td>
<td>
<code>org.blojsom.plugin.referer.BlogRefererGroup</code>
</td>
<td>Manages the referer groups for the various flavors setup in
<em>referer.properties</em>
</td>
</tr>
<tr>
<td>REFERER_MAX_LENGTH</td>
<td>Output</td>
<td>
<code>java.lang.Integer</code>
</td>
<td>Max length for referer URLs</td>
</tr>
</table>
</section>
</body>
</document>