This is an old revision of the document!
Table of Contents
dlcounter Plugin
Compatible with DokuWiki
Greebo
This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.
Purpose
The purpose of this plugin is to capture download information for some files in your media library. For example, you may wish to monitor the downloads for zip files. See the section on configuration to see how to specify which files data will be captured for. By default, this is zip, gzip and tar files.
The plugin can be used, but is not intended for, capturing download data on other files in your media library. You should be careful in configuring in order to avoid having the plugin record data for every image supplied with web pages.
Having captured data, you probably want to display it. You can fetch counts for individual files, or generate a table listing all the files downloaded since the plugin was installed. The plugin provides a rich set of syntax options for controlling the way the table looks.
Installation
Install the plugin using the Plugin Manager and the download URL above, which points to the latest version of the plugin. Refer to Plugins on how to install plugins manually.
Once installed and configured, the plugin will begin gathering data as files from the media library are downloaded.
Examples/Usage
To get the counter for a single file:
{{dlcounter>file?snow.zip}}
To list all the files with their counters in a table:
{{dlcounter>name?sort}} // table sorted by filename {{dlcounter>count?sort}} // table sorted by download count {{dlcounter>count?rsort}} // table sorted by download count in descending order
Syntax
Displaying a counter for a single file
If you just want to display the counter for a single file:
{{dlcounter>file?snow.zip}}
Command: file
Parameter: the name of the file you need data for
This returns a number (which could be zero if it hasn't gathered any data for the file yet). This allows you to bracket the data anyhow you like. The filename should include the list of namespaces, so you might want to check where it is stored in the media manager.
{{dlcounter>file?aardvark:mongoose:chainsaw:snow.zip}}
An example in a more realistic use-case:
..blah blah blah widget.zip ({{dlcounter>file?software:downloads:widget.zip}} downloads).
which might output:
..blah blah blah widget.zip (15 downloads).
Note that if you request data for a file that doesn't exist, the plugin returns zero and not an error. It only knows about files that have been downloaded since the plugin was installed, so assumes everything else hasn't been downloaded yet, whether it is a real file or you've typed the name incorrectly or provided the wrong path.
Displaying in Tables
You can also display the data in a table. For this, the command can either be name
or count
. There are a number of optional parameters to this command which affect the output:
SORTING sort => orders the data in ascending order rsort => orders the data in descending order FILENAME DISPLAY left => left-align the filenames center => center the names right => right-align the filenames strip => strip the path information to leave just the filename nobold => do not highlight the filename COUNTER DISPLAY minwidth => minimum width of the column cpad => left-pad the column with spaces HEADER DISPLAY hleft => left-align the header hcenter => center the header hright => right-align the header noheader => do not display a header htext => set alternate text for header
defaults:
sorting is in natural order (and may therefore change and is unpredictable)
alignment for filenames is right-justified
full path information is displayed
filename is emboldened (to help it stand out from path information)
header is displayed
header is centered
header text is Downloads
minwidth is 0 (meaning it is ignored)
cpad is 1
Note that if you use the strip
parameter to remove path information, the filename will still be emboldened unless you use the nobold
option.
Sorting is performed on the column named in the command, e.g. if you specify name?sort
, the filenames will be sorted, and count?sort
will result in the counters being sorted.
Parameters should be separated from each other by a space.
{{dlcounter>name?sort}} // sort by filename {{dlcounter>count?rsort}} // sort by counter in descending order {{dlcounter>name?strip left}} // natural order, no path info, left justified {{dlcounter>name?rsort strip}} // names in descending order, no path info
If you specify contradicting parameters, the rightmost will take precedence. e.g.
{{dlcounter>name?sort rsort}}
…the list will be sorted in reverse alphanumeric order.
When displaying the data in natural order, it doesn't make any difference whether you specify name
or count
as the command.
An example of table output:
{{dlcounter>count?rsort strip left tleft}}
Configuration and Settings
Configure the plugin in the admin screen. It's pretty much a doozy, just make a comma-separated list of the file extensions you want to capture download information for. The default is zip,gzip,tar
, but you might want to add pdf
and possibly a few others. Be careful not to include images and other media that get delivered as part of your web pages, else you'll end up gathering data on a whole bunch of stuff you never intended to.
The extensions should be named without a preceding period, so zip
is correct, .zip
will be an epic failure.
The plugin only collects information on files delivered from the media library. Super-user rights may be needed to upload large files into the media library. If you are unaware, the primary Admin for the wiki can usually ignore the 2Mb limit on uploads.
Change Log
- 2019-05-14
- Initial release
Known Bugs and Issues
No known bugs.
There is a minor issue you should be aware of. When tables are sorted on names, the filename includes the entire path, so it is possible that files might seem out of order, especially when you strip the paths. If you take the paths into consideration, you'll find the files are in the correct order.
If there is enough interest, I'll get around to fixing that issue, but it's not an issue for me. If you want it fixed, visit the site below and leave a comment.
FAQ
Full documentation including how to access the datastore can be found here.
Comments, suggestions and bug reports can be filed here