Drain Hole Plugin
Drain Hole is a centralized download manager, with full monitoring and statistics, versioning, SVN support, and SEO download URLs (no more nasty query strings!).
In addition to it's monitoring abilities, Drain Hole has a run-time tag replacement feature that lets you embed special tags in your post which are replaced with information from Drain Hole. For example, you can embed download URLs, version information, last update times, and so on. Whenever you change a downloadable file it is automatically updated throughout your blog, without you needing to change anything else.
Features include:
- SEO download URLs - a unique feature that allows files to look like real links
- SVN support - attach a file directly to an SVN repository and have the contents automatically updated
- Versioning - maintain multiple versions of a file, allowing users to download older files
- Full download statistics, including number of downloads, access times, referrer, and download speed, available as CSV and Flash-based graphs
- Download security - permissions can be assigned to downloads (including Flash files), restricting them to WordPress roles
- Template tags - insert dynamic download data into posts, and into the sidebar as a Widget
- Hot-link protection
- Fully localized
Version History
- 2.1.12 - Allow for sites with open_basedir restrictions
- 2.1.11 - Update plugin base class
- 2.1.10 - Add file modification time
- 2.1.9 - Fix problem with truncated URLs on some sites
- 2.1.8 - Fix typo in mime type
- 2.1.7 - Fix spaces in version numbers
- 2.1.5 - Better custom 2.6 support
- 2.1.4 - Scanning fix
Installation
Installation is like any WordPress plugin:
- Download drain-hole.zip
- Unzip
- Upload drain-hole directory to
/wp-content/pluginson your server - Activate the plugin
- Use Drain Hole from the Manage/Drain Hole menu
You can find full details of installing a plugin on the plugin installation page. SVN access to the plugin is provided at the SVN repository.
General Concepts
The Drain Hole plugin makes use of two fundamental concepts:
- Drain hole - a base URL and associated directory where files are stored and downloaded from
- Files - a file belongs to a particular Drain hole
It is important to understand the mapping between a Drain Hole's URL and its associated directory. To do this you need to know two pieces of information:
- Where files are to be downloaded from (i.e.
http://urbangiraffe.com/download/) - Where files are to be stored (i.e
/users/john/download/)
This is a mapping from URL to directory:
http://urbangiraffe.com/download/ => /users/john/download/
All files inside the directory will be available at the Drain Hole URL. For example:
/users/john/download/myplugin.zip => http://urbangiraffe.com/download/myplugin.zip
It is preferable that your directory is not in a public location (i.e. in public_html) as Drain Hole may not then be able to function. Your URL must be part of your WordPress installation, but you should not create a directory for it.
Creating a Drain Hole
New Drain Holes require the following information:
The URL is the URL on your website at which to make the files available. The directory is the real directory in which the files exist. These two values do not have to match up and the files do not (and ideally should not) be publicly available.
Once a Drain Hole has been created you can then edit it from the list of Drain Holes:
Editing a Drain Hole will allow you to set additional options:
The Access Level is the minimum user level required to download files from the hole. This allows you to restrict download access to certain types of user. If a user does not meet the required access level then they will be returned a 404 error page or will be redirected to the configured URL.
The Stop Hot-links option allows you to stop external users from downloading files in the hole. This protection is achieved by analyzing the referring page for a given download - if the referrer is not from your site then the user is sent a 404 error page or redirect to the error URL.
Files
A Drain Hole can contain any number of files and sub-directories.
As with the rest of the plugin, columns are sortable, and data can be searched.
Each file allows you to:
- Edit the file configuration
- Manage version history (by clicking on the version number)
- View download statistics (by clicking on the number of hits or the charts link)
- Create a new version or update from SVN (by clicking on the branch link)
When editing a file you will be shown additional configuration details:
The filename is the actual name of the file and this may differ from the name, which is what will be shown in a download link. If no name is given then the filename will be used. As an extra function, you can insert $version$ into the name and it will be replaced with the file's current version.
The description is a free-form field allowing you to enter further details about the download. This can be shown when the file is displayed.
The SVN field allows you to enter an SVN repository. See the SVN section later.
When displaying a file to download, an icon can be shown. You can change which icon is shown when editing a file.
The MIME type allows you to specify a custom MIME type for the file. This may be useful if you want a file to open inside the browser. If set to 'automatic' then Drain Hole will try and decide what the file is.
Forcing a download allows you to override default browser behaviour and force the file to always be downloaded. This is useful if you have a file that a browser usually tries to open (for example, a PDF), but you want it to always be downloaded.
Forcing the access level is an advanced option that is useful if you are trying to restrict files that are used inside Flash. For example, you may have a video tutorial that you want to restrict to registered users only. The flash video player requires your video file to be available, but may not provide any restriction options. Storing the video inside Drain Hole and then forcing the access level will ensure that only allowed users can access the file, even inside Flash.
Adding new files
New files can be added by any of these methods:
- Uploading a file directly into the Drain Hole directory and 'rescanning'
- Uploading a file through the browser
- Creating an empty file which can be uploaded later, or which requires an SVN repository
Versions
Drain Hole allows you to retain old versions of files, either for archiving purposes or for user downloads. To modify a file's version you need to create a new branch:
You can enter details about the reason for the new version, and this will be presented to the end user. To retain an old version you must check 'retain old version'. This old version can be downloaded as follows:
http://urbangiraffe.com/download/myplugin.zip?version=1.2
SVN
Drain Hole provides simple SVN functionality that allows you to associate a file with an SVN repository. A file that uses SVN can then be 'refreshed' directly from the SVN repository, rather than requiring you to manually update the file.
SVN functionality requires that you have SVN installed on your host. You must configure the Drain Hole options and provide the full path to the svn executable. If you are in doubt you should consult your host for details.
When an SVN-based file is refreshed, Drain Hole will use SVN to retrieve the latest copy of the files. If a repository contains multiple files they will be automatically zipped.
As additional functionality, Drain Hole will detect if the SVN repository is for a WordPress plugin, and will automatically set the version according to the version information inside the plugin.
Note that no direct capabilities are provided for username and passwords. However, you can pass a username and password to SVN by including it on the SVN field:
http://svn.mysite.com/plugin/trunk/ --username=john --password=thing
Download Tags
The following tags can be inserted inside posts and pages to embed Drain Hole information. This information is generated dynamically, and will change whenever the underlying information changes:
[drain hole ID hits]- Displays the total number of hits from the specified hole ID[drain hole ID show]- Show a list of all files in the specified hole (change display code by copyingview/drain-hole/show_hole.phpfrom the Drain Hole plugin directory to the same directory path in your theme's directory and editing the file)[drain file ID show template]- Displays the download template for the specified file ID. 'template' is optional and can be ignored (the default template will be used)[drain file ID version]- Displays the version of the specified file[drain file ID versions limit]- Displays the specified number of versions from the file's history[drain file ID hits]- Displays the total downloads for the specified file[drain file ID url name]- Displays a URL allowing the specified file to be downloaded. 'name' is optional and is the text that will appear inside the download link (if not specified then the filename is used)[drain file ID updated]- Displays the update time of the specified file[drain file ID size]- Displays the size of the specified file[drain file ID icon]- Displays the download icon for the specified file[drain file ID href]- Displays the URL of the file
Where ID refers to the ID of the file or hole, as shown in the Drain Hole administration pages.
Download Templates & File Icons
A download template is a section of HTML code that is used to display all the information for a file download. For example, on this page in the top right corner is the download for Drain Hole itself. The icon and file information are all part of a download template that is re-used on each of the other plugin pages available from this site.
A download template is a file that is stored in your theme directory and contains standard HTML as well as special Drain Hole template tags:
$icon$$url$$version$$updated$$size$$href$
These template tags function similar to the post & page tags, but do not require an ID to be specified.
A default template is provided with Drain Hole. Custom templates are PHP files that are stored in view/drain-hole, inside your theme directory. For example, if you are using the default WordPress theme then:
/wp-content/themes/default/view/drain-hole/mytemplate.php
To use this template in a post you would insert the tag:
[drain file 5 show mytemplate]
This tells Drain Hole to use 'mytemplate.php' to display file 5.
Custom icons can be stored inside your theme:
/wp-content/themes/default/view/drain-hole/icons/
Statistics
Drain Hole provides full download statistics:
FAQ
If you have any questions or problems then please consult the Drainhole FAQ before posting here.
Support
Please direct all support questions to the Drain Hole support forum. Any support questions left on this page may not be answered.
Bugs & New Features
A full list of all bugs can be found in the Drain Hole issue tracker.
| Date | Current outstanding bugs | Status |
|---|---|---|
| 19 Nov 2008 | Error 404 & Chart timeout |
A full list of all requested features can be found in the Drain Hole feature tracker.
| Date | Current requested features |
|---|---|
| 14 Sep 2008 | Multi-stage download |
| 07 Oct 2008 | Paypal access |
| 03 Nov 2008 | limited access to drain hole(s) |
| 08 Nov 2008 | Link to Amazon S3 |
Comments (page 15 of 31)
Dec 1, 2007 4:36 pm
Great tool. Thanks!
Can you tell me how to manually call the widget on a page? I use a custom theme that is not widget ready and dont want to hack it to add widget support.
Thanks.
Nov 29, 2007 8:18 pm
Hello everyone
I see that this issue has come up before.
So this is a revisted of sorts from some of you.
I'am using WP 2.2+ with latest drain hole.
Unsuccessful as of yet with my exsiting configuration.
url:/download/files
directory: /home/lightconecorp/download/files
This message pops-up below after selecting the jpg link for download.
"The document you requested is not found on this server."
http://www.lightconecorp.net/download/files
The above url I'm trying to get to work.
I deactivate Redirection 1.7.2.6, No joy there.
In search of clues here.
Very impressive software work John.
Thanks
P.S.
Message for today, support open source programming
Donate
Nov 29, 2007 7:04 am
Hi John,
I want to display the file version while using [drain hole ID show].
What is the code to place into show_hole.php?
Nov 28, 2007 8:00 am
Sorry, this is the code:
<?php if (!empty ($files)) : ?><?php foreach ($files AS $file) : ?><?php echo $file->url ($hole, $name->file); ?> (<?php echo $file->bytes ($file->filesize ($hole)) ?>)
<?php if ($file->description) echo ''.$file->description; ?>
<?php endforeach; ?><?php endif; ?>Nov 28, 2007 7:58 am
Hi friend,
Thanks for the great plugin.
I made some changes in show_hole.php file to look better on my site, like show the name instead of the filename but the list of files are not ordered alphabeticaly... may you help me?
here is the code:
Nov 27, 2007 7:41 am
It would be great if Drain Hole could restrict file requests to one at a time per IP, or something. I'm getting hammered by download managers/accelerators which request the same file tens or hundreds of times per minute, and can't keep up with all the user-agent descriptions to ban them. Is this possible?
Nov 27, 2007 7:27 am
Hey John,
If someone were to create patches for Drain Hole to add the following functionality, would you incorporate them into the main plugin?
Possible functionality:
Add ability to assign screenshots to a file. (create a new table and link screenshots to file IDs)
Add ability to change the Download icon to a custom one (instead of having to choose from the predfined ones)
I think Drain Hole is an awesome plugin, and by adding the functionalities above, it could be a powerful solution to easily create "file download" sites with Wordpress.
Nov 26, 2007 9:44 pm
Adam, it seems your host has blocked the 'escapeshellcmd' function, which Drain Hole is using. I've added a check in the code for this so the error will disappear.
Steven, those database errors you reported are from some other download manager!
Chio, you should use a relative URL, not an absolute URL. Currently you have the URL setup as /http//www.funkymovie.com/download - change this to just /download/
Nov 26, 2007 4:34 pm
Thanks for the great plugin!
I'd like to offer a "smart" hotlink protection. Now you check the referer. But if the user for example copy-pastes an url to the location bar, the script will refuse to provide the file. The same with download managers.
What if you put a cookie when the user opens any wordpress page. The life of the cookie will be the current browser session. When a file is requested, the script will check if our cookie is in place. This way we can solve the problem with the copy-pasted url and with those download masters smart enough to pass the cookie to the server.
Slava.
Nov 25, 2007 1:02 pm
Okay I figured out what my problem was. I will explain my problem and the solution for those who may be reading this and having the same problem.
I was having the 404 error that many people have mentioned and I thought the script just wasn't redirecting. What I discovered is that the script was redirecting it was just being stopped by my .htaccess file which was in the subdirectory of my website, where I installed Wordpress.
For example:
Website: http://www.example.com
Wordpress installation: http://www.example.com/blog/
Wordpress automatically creates an .htaccess file to control redirections associated with pages and posts you have created and to coincide with the permalinks structure you have established. The .htaccess file looks like this:
RewriteEngine On
RewriteBase /blog/
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /blog/index.php [L]
# END WordPress
To fix the error, you need to COPY this file and change it to look like this:
# BEGIN WordPress
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /blog/index.php [L]
# END WordPress
Notice immediately after "RewriteBase" the change. It is now on the ROOT directory and not a SUBdirectory.
After you have made the change, add the new COPIED file to the ROOT directory of your site, i. e. - http://www.example.com/ or home/username/public_html/website/
The idea is to make sure it is on the ROOT directory and not a subdirectory.
Be sure to NOT change or move the original .htaccess file created by Wordpress, because this is still needed in order for your Wordpress installation to work properly. You will now have two .htaccess files now, one in the subdirectory with your Wordpress installation and the other under the root directory of your site.
If you need further info about .htaccess files, do a search on Google.
Well, I hope this helps someone.
Lee
P.S.- This is just one solution that helped me and hopefully others, you still have to install Drain Hole correctly.
Leave a comment