Auto Navigation Plugin

This plugin displays an automatically-generated "quick links" bar pointing to commonly viewed topics.

Features

Tracks the pages that are commonly accessed, and makes a "quick links"-style navigation bar out of them.

Syntax Rules

Write the command %AUTONAV% anywhere in a TWiki topic. Generally, you will want to put this somewhere like WebLeftBar in the PatternSkin.

Preferences

Variables

These are the variables that control the operation of the plugin:

• Cache settings. This plugin takes a bit of time to calculate the page rankings it uses. The first time it is run, and every %MAXCACHEAGE% seconds thereafter, it will recalculate its rankings and store them on disk; this can take several seconds. You may disable the on-disk cache by setting CACHE to off (thus recalculating rankings with every page view), but this is not recommended, because it will make your twiki slow.
  • Set CACHE = on
  • Set MAXCACHEAGE = 7200

• Display settings. These control how the plugin displays its results. NUMTOPICS is the number of topics to put in the list.
  • Set NUMTOPICS = 30

• Context settings. These affect how the plugin decides which topics to display. The plugin chooses topics that have been consistently popular within at least one context it's been configured to use; by default, it evaluates topics within all of the following contexts:
  • any, which chooses any topics which are frequently accessed.
  • user, which chooses topics which are frequently accessed by the current user. You may also specify, for example, user:jsmith to get a specific user's context.
  • user_recent, which chooses topics which have been frequently accessed by the current user in the last 5 days. You may also set this variable as (e.g.) user_recent:3 to make it the last 3 days, or user_recent:4:tbrown to get a specific user's recent documents.
  • related, which chooses topics which are frequently viewed at about the same time as the current topic. You may also specify, for example, related:/cgi-bin/twiki/view/Main/WebHome to show topics that are related to a topic other than the current topic.
• The %CONTEXTS% variable should be a comma-separated list of which contexts to use. The order is not important.
• Set CONTEXTS = any,user,user_recent,related

• Logfile settings. The plugin expects to read apache logfiles to determine what topics have been popularly accessed. LOGFILE indicates that base logfile path to use, and NUMLOGS specifies to number of rotated logs to read.
  • Set LOGFILE = /var/log/apache2/access.log
  • Set NUMLOGS = 4
  • For example, the settings above will read the following logfiles:
    • /var/log/apache2/access.log
    • /var/log/apache2/access.log.1
    • /var/log/apache2/access.log.2.gz
    • /var/log/apache2/access.log.3.gz

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Display an auto-generated "quick links" bar listing commonly viewed topics

Which URLs to index

You may choose any URLs to go in the navigation this plugin generates; you are not limited to indexing twiki's pages. Each type of page indexed by this plugin is referred to as a "scope," and can be configured separately (i.e. it can sort and display with independent configuration). For example, for twiki, we will want two scopes: one for displaying ordinary topics, and a second (with different display settings) for WebHome topics.

The meaning of the various columns of this table are as follows:

• SCOPE is an identifier of the scope
• URL is a regexp matching the URLs of pages that should be indexed according to this scope. This regexp should not include the ^ and $ symbols, but nonetheless it must match the entire URL (you may wish to follow it up with \S* in some cases). Remember that if multiple distinct URLs match the same scope, they will be treated as separate pages (e.g. /cgi-bin/twiki/view/Main/WebHome and /cgi-bin/twiki/view/Main/WebHome?skin=dragon), so it is probably best to be strict about which URLs you match.
• PARENT is an identifier of the current scope's hierarchical "parent," if any. This is used to arrange the topics into trees, which are then displayed in prefix traversal order. For example, below, each wiki topic is configured with the WebHome topic as the parent, so that the final list of topics will be grouped by web (with the WebHome at the top of each web's group). Additionally, a separate scope matches the Demiurge WebHome, with the SORTORDER set such that that web will be displayed before all of the other webs.
• FORMAT is the format for displaying results from this scope.
  • $n may be used to insert a newline.
  • $1 may be used to refer to the first parenthesized expression from URL, and so on for further integers.
• SORTORDER is the sorting order to use for comparing topics to each other. This is only to used to compare siblings to each other; the hierarchy generated by the PARENT setting is still responsible for the bulk of the arrangement of the items. If the SORTORDER for two siblings is the same, they will be sorted by their URLs. All sorting is done alphabetically, NOT numerically.
• OPTIONS is a comma-separated list of miscellaneous options. Currently, there is only one supported:
  • twikihack means to check that the current user is able to read the $2 topic in the $1 web before displaying the link.

You must not change the title of the following table, or the names of any of its columns.

AUTONAVSCOPESTABLE
SCOPE	URL	PARENT	FORMAT	SORTORDER	OPTIONS
demiurge	/cgi-bin/view/(Demiurge)/(WebHome)		---$n * $1 Web$n	aa	twikihack
webhome	/cgi-bin/view/(\w+)/(WebHome)		---$n * $1 Web$n	bb	twikihack
wiki	/cgi-bin/view/(\w+)/(\w+)	/cgi-bin/view/$1/WebHome	$sp$sp$sp* $2$n		twikihack

Topic lock

This plugin operates in some dangerous ways; it's possible to use it to spy on other users, for example, or to set %LOGPATH% to a value that could cause security problems. Therefore, this is essential:

• #Set ALLOWTOPICCHANGE = TWikiAdminGroup
• #Set ALLOWTOPICRENAME = TWikiAdminGroup

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

• Download the ZIP file from the Plugin web (see below)
• Install the Date::Parse module from CPAN or your vendor.
• Unzip AutoNavigationPlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/AutoNavigationPlugin.txt	Plugin doc page (this page)
  lib/TWiki/Plugins/AutoNavigationPlugin.pm	Plugin perl module
  lib/TWiki/Plugins/AutoNavigationPlugin/Scope.pm	Plugin perl module
  lib/TWiki/Plugins/AutoNavigationPlugin/Cache.pm	Plugin perl module

• Set $TWiki::cfg{Plugins}{AutoNavigationPlugin}{Enabled} = 1; in your LocalSite.cfg configuration file.
• Change the permissions on your Apache logs (generally /var/log/apache/access.log or similar) to be readable by your Apache group or user, such as nobody or www-data.
• Configure the preferences and navigation configuration above.
• Add the %AUTONAV% tag to one of your templates, if desired -- for example, you may replace part of WebLeftBar with it.

Test

This should show the automatic navigation bar:

%AUTONAV%

Troubleshooting

AUTONAV tag doesn't expand

Check in your apache/error.log and twiki warning log files; there will be more information there about precisely what went wrong. Probably your configuration is not set up correctly yet.

Plugin work directory doesn't exist

If you get a "500 internal server error" and find something like this in your apache error.log:

RCS: failed to create AutoNavigationPluginwork area: No such file or directory at /usr/share/perl5/TWiki/Store/RcsFile.pm line 222.

... then your work directory doesn't exist. The work directory is configured in /etc/twiki/TWiki.cfg as $TWiki::cfg{RCS}{WorkAreaDir}; you should create it (making sure that it's in a place that isn't served as web content by your web server), and make it owned by your webserver user, such as nobody or www-data.

Plugin Info

Plugin Author:	v0.3 TWiki:Main.AndrewMoise
Copyright:	© 2006, TWiki:Main.AndrewMoise
License:	GPL (GNU General Public License)
Plugin Version:	0.3.2
Change History:
4 Sep 2006	0.3.2 Fix warnings in apache error.log
4 Sep 2006	0.3 More code cleanups, fix failure when user isn't logged in
16 Aug 2006	0.2 Code cleanups and speedups
13 Aug 2006	0.1 Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	Date::Parse
Other Dependencies:	none
Perl Version:	5.0
Benchmarks:	GoodStyle 97%, FormattedSearch 99%, AutoNavigationPlugin 90%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/AutoNavigationPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/AutoNavigationPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/AutoNavigationPluginAppraisal

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.AndrewMoise - 13 Aug 2006