DLCounter Plugin

This download-counter plugin for DokuWiki enables you to keep track of the number of downloads of media files such as zip, gzip, tarballs and pdf's (your choice of media formats). This plugin has been developed and tested on “Greebo”, it may not work with older versions of DokuWiki. It has worked on all versions since, up to and including “Kaos”.

This page is the documentation for this plugin, describing configuration, the syntax for displaying the data (or parts of it) and the on-disk format of the data-store and how to access it from your own (possibly inline) code should you need to.

The data is stored in a folder named 'counts' off the data folder, so it gets backed up when you backup your data folder (you do that, don't you?).

• Fixed Admin menu display and output (2024/07/27 13:38)
• Update README.md (2024/06/22 13:28)
• Update README.md (2024/06/22 12:53)

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

For manual installation, the latest version of the package can be downloaded here (local copy) or downloaded here (github repository).

The plugin has an entry on the Admin page. This now works, and displays a list of all the files downloaded from the media library that you have been tracking (see Configuration below). Remember that it can only display items that have been downloaded - files that haven't it doesn't know about. The list is sorted by file name.

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.

Collecting all this data isn't much good if you can't use it. You can display the data in a number of ways.

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.

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. Sorting on names uses the filename first and the path as a subsort.

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 hleft}}

results in:

For aesthetic reasons, you may wish to set the minimum size of the counter column. To do this, use this syntax:

{{dlcounter>name?minwidth=3}}

It doesn't matter which command you use (name or count).

You can also use the cpad option to adjust the width of the column. Where minwidth only comes into force if no number is as large as minwidth, the cpad option always left-pads the column. Semantically, these two options are the same as:

<td style='min-width: 1em; padding-left: 1em;'>

…where the 1em would be replaced by the values you specify. The numbers are expressed in em, which equates to a full-width character.

To understand how these work together, imagine you have a counter with the value 99, and you have set minwidth=3 and cpad=2. The number is 2 characters wide, therefore minwidth will add a full-width blank space in front of the number. Since cpad is always enforced, it will add two more full-width spaces. This means the cell will in fact be 5 characters wide.

If the number was 1000, minwidth would be ignored, cpad would add two spaces and the cell would be 6 characters wide.

To specify a different header, use the following syntax:

{{dlcounter>name?htext="This is the new text"}}

You must use double-quotes, not single-quotes, to encapsulate the new header text. There should be no spaces between htext and =, or between = and the text. Quotes are required, even when the new text is a single word.

If you want to format the data to your own liking, you can fetch the data from the file data/counts/download_counts.json off the root of the DokuWiki installation. You should use file_get_contents() to open, read and close the file as quickly as possible.

$fname = DOKU_INC."data/counts/download_counts.json";
$assoc = json_decode( file_get_contents($fname), TRUE ); // fetch data as an associative array
$json  = json_decode( file_get_contents($fname) );       // fetch the data as a json object

The data is stored in simple key/value pairs with (surprise!) the filename being the key. The filename includes the path information in colon-separated format: path:to:filename.zip

Note the plugin can't actually tell if a file was downloaded. If someone clicks the link to download a file, and then clicks cancel on the Save As… dialog, the plugin will never know. All it can do is register the click that initiates the download (no event is generated for successful delivery).

This actually makes it easy to test. Click a link to download and cancel on the Save As dialog, and repeat this a few times to generate some stats for yourself. When you're done testing, navigate to the counts folder as outlined above and delete the download_counts.json file to reset.

The plugin will automatically create the data/counts folder if it doesn't exist. It sets the folder permissions to 0755 for operating systems that support it. If you want other permissions, you can either create the folder ahead of installing the plugin, or change the permissions using your favourite tool after it has been created. Just make sure you don't deny DokuWiki access or read/write permission to it, else there will be tears.

The folder is created when it is needed, so won't be created until someone downloads something.