Wordpress Download Monitor 3 Documentation

Installation

If you have not already installed it, to install download monitor unzip the plugin file and put the download-monitor folder into your plugins directory. Activate it and your away. Once activated Download Monitor will create the database tables and set things up.

You will find the admin interface for download monitor on the top level menu listed as ‘Downloads’.

Configuring Download Monitor

Go to the Downloads > Configuration page. Here you will find the following sections.

Download categories

You can categorise downloads using the categories you define in this section. Note that they can be nested. Each download may have only one category. To add a category, input its name and choose a parent (if you want to nest it), then click Add.

Note each category has an ID; this is how you will reference the category when displaying them in posts.

Custom Output Formats

This is where you define how your download links will look. Custom formats should be written as HTML and also use special ‘tags’ which get substituted for download information when shown. The following tags can be used when defining a custom format; each is replaced with the download’s information.

• {url} – Url of download (does not include the actual hyperlink)
• {version} – Version of download
• {version,"before","after"} – Version of download. Not outputted if none set. Replace “before” with preceding text/html and “after” with succeeding text/html.
• {title} – Title of download
• {size} – Filesize of download
• {category,"before","after"} or {category} – Download Category. Replace “before” with preceding text/html and “after” with succeeding text/html.
• {hits} – Current hit count
• {hits,"No hits","1 Hit","% hits"} – Formatted hit count depending on hits. % replaced with hit count.
• {image_url} – URL of the download image
• {description,"before","after"} or {description} – Description you gave download. Not outputted if none set. Replace “before” with preceding text/html and “after” with succeeding text/html.
• {description-autop,"before","after"} or {description-autop} – Description formatted with autop (converts double line breaks to paragraphs)
• {date,"Y-m-d"} – Date posted. Second argument is for date format.
• {meta-key} – Custom field value
• {meta-autop-key} – Custom field value formatted with autop

For example, if I wanted to output my download with an image button I would use the following custom format:

<a href="{url}" title="Downloaded {hits} times"><img src="{image_url}" alt="{title}" /></a>

In this example I output a download link, with it’s title as the link text, followed by a description:

<a href="{url}" title="Downloaded {hits} times" >{title}</a> - {description}

Like categories, custom formats are referenced by ID, not by name.

Using custom formats gives you the flexibility to output downloads however you please, be it as links, list items, or table rows – the sky is the limit.

Custom Download URL

This option allows you to mask the download URL to something that looks a bit nicer. By default the download url will be something like:

http://yourdomain.com/wp-content/plugins/download-monitor/download.php?id=1

By entering something in the first input box you can mask the first part of the link. For example, if I added downloads/ as the custom url my links would look like this:

http://yourdomain.com/downloads/1

The dropdown option (which defaults as ID) chooses the final part of the link. For example, if I selected ‘filename’ from the dropdown and clicked save I would now have links like this:

http://yourdomain.com/downloads/filename.zip

Important: Do not make the custom url match a real url e.g. do not call it downloads/ if you really do have a directory called downloads on your server, because this will cause conflicts and break your links.

You must re-save your permalink settings after updating custom urls for your settings to take effect.

General Options

• “Download not found” redirect URL - (optional) If set, when a download is not found the user will be redirected here.
• Member-only files non-member redirect: - (optional) If set, if a user tries to download a member only file and is not logged in they will be sent to this page.
• Download image path – The path of the image for the {image_url} custom format tag.
• Default output format – (optional) The custom format to be used if you don’t specifically reference one when outputting a download.

Recreate Download Database

If you experience problems, such as not being able to add a download, it may be the database at fault. This option reinstalls the database tables (backup your database before using this function).

Top

Adding & managing your downloads

Downloads can be added in one of three ways;

1. Using the Downloads > Add New page to upload and add a file.
2. Using the Downloads > Add Existing page to choose an already uploaded/remotely hosted file.
3. Using the uploader on a posts screen (see section below: ‘Using the post page uploader’)

The ‘add download’ forms should be pretty self-explanatory, however, I will explain custom fields and member only files in a little more detail. New downloads are uploaded to the wp-content/uploads/xxxx/xx directory (like images are when inserting images into posts).

Custom fields allow you to define additional data about your downloads – just add a ‘name’ and a ‘value’. You can then reference this data using custom formats ({meta-key} and {meta-autop-key}). They have all kinds of uses, for example, if I wanted to include a thumbnail for each download I could add a custom field called ‘thumbnail-path’. I could then use a custom format to output the thumbnail like this:

<a href="{url}" title="Downloaded {hits} times"><img src="{meta-thumbnail-path}" alt="Thumbnail" /> {title}</a>

Each download can have as many custom fields as you want.

The Member only file option, when enabled, only allows logged in users to download the file in question. If they are not logged in they will see a message telling them this *or* will be redirected to the Member-only files non-member redirect url set on the configuration page.

One handy additional feature with member only files is that if you give a download a custom field called min-level; the user will need to be this level or higher in order to access the file.

Viewing, editing and deleting downloads

All downloads can be viewed on the main download monitor admin page (as well as hits) and can be edited by clicking the edit icon on the right. The edit screen works in a similar fashion to the add download page. You can also delete downloads from here – this also removes the file from the server if you uploaded it via the ‘Add new’ page.

Download Logs

The Downloads > Log page shows a list of recently downloaded files, along with user ID’s/IP addresses. This is not used for stats so the log can be safety cleared using the ‘clear log’ button if you wish.

Download Stats

It has already been mentioned that you can view hits on the view downloads page, however, if you visit your admin dashboard you will notice two additional stats widgets. One shows the top 5 downloads, where the other lets you select a date range and a download to view daily/montly download stats.

widget-screenshots

Using the post page uploader

On the wordpress post screen you will notice a small ‘arrow’ icon near the insert image button above the editor – this allows you to access download monitor conveniently when posting.

uploader-icon

From this screen you can add a new file (and insert into the post), or by clicking ‘view downloads’ you can see the list of files and click ‘insert’ to insert them into your post.

Note: It is normal for the inserted code to look something like [download id="1"]. This is parsed when the post is viewed.

Top

Outputting your Downloads

Download monitor provides a variety of ways to output your downloads in your pages, posts, or templates.

Shortcodes

Shortcodes are the best way of including downloads (these replace many of the legacy tags shown later).

Outputting a single Download

[download id="1" format="1" autop="false"]

This shortcode outputs a single download of your choosing (set the id), with an optional custom format (replace the id in ‘format’), and an optional autop (true or false; false prevents wrapping the outputted content in p tags and is default). Valid examples:

[download id="1"]

[download id="2" format="2"]

Outputting multiple downloads

[downloads query="limit=5&orderby=rand" format="1" wrap="ul" before="<li>" after="</li>" autop="false"]

This shortcode retrieves and outputs multiple downloads in posts. All of the options are optional.

‘query’ takes a query string containing a variety of options (see the get_downloads() function below; they use the same query string format). By default it retrieves 5 random downloads. A common request is showing a category using this shortcode; to do that you can add &category=1 (replacing 1 with the category ID) to the query string.

‘Format’ take a custom format ID to change how the downloads of outputted.

‘Wrap’ by default wraps the downloads in a unordered list; you can set this option to be blank if you want to wrap it with something else (like a table).

‘Before’ and ‘after’ are what each download will be wrapped in (by default this is a list item). If you modify these values you must ensure the code you insert is encoded e.g. replace < with <.

‘autop’ can be true or false; false prevents wrapping the outputted content in p tags and is default.

Valid examples:

[downloads]

[downloads query="limit=5&orderby=hits"]

[downloads query="limit=5&orderby=hits" format="2"]

[download query="limit=5&orderby=hits" wrap="" before="<p>" after="</p>"]

Show a special download page

Use the [download_page] shortcode. See the ‘download page’ section for more info.

Parsing shortcodes in templates

Did you know you could output shortcodes in places other than posts? Just wrap your shortcode in the do_shortcode() function. Example:

do_shortcode('[download id="1"]');

get_downloads() template function

This function returns downloads that match your query; it takes 1 argument containing the query string. The defaults are as follows:

'limit' => '', 'offset' => 0, 'vip' => 0 'category' => '', 'orderby' => 'id', 'order' => 'ASC'

As with many of wordpress’ functions, construct your query string using the above attributes linked together with an ampersand (&), e.g. limit=5&orderby=hits&order=desc.

‘limit‘ takes an integer and will return that many posts.

‘offset‘ takes an integer and will offset the returned posts by that number. e.g. offset of 1 would not return the first result.

‘vip‘ can be 1 (true) or 0 (false); if set to true, only downloads you have permission to access will be displayed (non members will not see member only downloads).

‘category‘ takes a comma separated list of category id’s and returns downloads in those categories.

‘orderby‘ orders the downloads. Valid options for this include id, hits, title, date, filename, and random. NEW: can also be ‘meta’

‘meta_name‘ define the meta field to sort by when using orderby=meta. Only downloads with this meta field will show.

‘order‘ can be ‘ASC’ for ascending, and ‘DESC’ for descending.

get_downloads() returns an array object with the following data:

• size
• url
• title
• version
• hits
• image
• desc
• category
• category_id
• id
• date
• memberonly

Usage Example: (Output a list of top downloads)

$dl = get_downloads('limit=5&orderby=hits&order=desc');
 
if (!empty($dl)) {
    echo '<ul class="downloadList">';
    foreach($dl as $d) {
        $date = date("jS M Y", strtotime($d->date));
        echo '<li><a href="'.$d->url.'" title="'.__('Version',"wp-download_monitor").' '.$d->version.' '.__('downloaded',"wp-download_monitor").' '.$d->hits.' '.__('times',"wp-download_monitor").'" >'.$d->title.' ('.$d->hits.')</a></li>';
    }
    echo '</ul>';
}

Top

FAQ

My Downloads don’t work or the download page is not found/error 500’s, wtf?

Several reasons can cause this. First things first – check the plugin folders permissions. The folder and files should be readable – especially download.php so check! Also, avoid setting to 777 at all costs. Second, resave permalink settings – this can often cause hiccups. Finally, check the path to the download is correct by editing it – try entering the url directly into the address bar. If its not found, you cannot blame the plugin!

My hits are not showing up! Help?

Admin hits are not counted, log out and try! Also ensure that if you have set the ‘custom url’ option that the custom url does not actually match the physical location of the file.

I have wordpress installed in a sub directory and my downloads don’t work

Go to settings > misc in wordpress admin and check the ‘Store uploads in this folder’ setting is correct. Sometimes wordpress screws this up. You may also notice that normal uploads in wordpress (e.g. via the media panel) don’t work correctly either if this setting is wrong.

I get an ‘error saving to database error’. What’s happening?

The download tables may not exist. Use the option in Downloads > configuration > Recreate Download Database.

My member only downloads are corrupted/don’t work, why?

To hide the URL, member only downloads are forced by using PHP’s readfile function. If the download is hosted externally, or the server does not support it properly the download may be corrupted. To turn off forced downloading add the custom field ‘force’ to the download and set it to ‘0′.

I want my downloads to be parsed in a custom field using get_post_meta(), can I do this?

Wordpress does not have a filter I can hook into for this function, so to make this work wrap it in the relevant functions. For old style download links ([Download id not defined]) use wp_dlm_parse_downloads() else use do_shortcode(). For example:

echo do_shortcode(get_post_meta($post->ID, 'Download', true));

What happened to the old tags?

They still exist – they are just no longer supported. See below.

The following (older) tags will work in your posts but are no longer supported (shortcodes are now preferred). These are mainly here for backward compatibility.

Output a download with a custom format:

Use the admin panel to define custom formats to output your links and then use [download#id#format=id] or just [download#id] if you set one as default.

Other output functions:

To show download links, use the following tags:

1. Link/hits – [download#id]
2. Link w/o hits – [download#id#nohits]
3. URL only – [download#id#url]
4. Hits only - [download#id#hits]
5. Link with image – [download#id#image]
6. Link/hits/filesize – [download#id#size]
7. Link/filesize – [download#id#size#nohits]

There are a few other template tags to use in your wordpress templates. Replace ‘$no’ with the amount of downloads to show.

1. Most downloaded – <?php wp_dlm_show_downloads(1,$no); ?>
2. Most recent – <?php wp_dlm_show_downloads(2,$no); ?>
3. Random – <?php wp_dlm_show_downloads(3,$no); ?>

Show all downloads:

Add the tag [#show_downloads] to a page.

Show downloads with category selector:

Add the tag [#advanced_downloads] to a page.

Show downloads in a single category:

Use [download_cat#id] replacing id with the id of the category.

Top

Download Page

I gave in. I was going to release this as a paid add-on, but I’ve changed my mind because I trust you guys to make donations to ensure support continues for this plugin. So here we go; the download page addon (as seen on this site in the ‘Downloads’ page) is now built into download monitor (version 3.1 +). The download page includes a sorting, pagination, and search function.

Usage

To create a download page, first create a wordpress page (or post) and insert the following shortcode:

[download_page]

Easy huh? But theres more. This shortcode has the following options:

• base_heading_level (integer) – Category headings on the page are this level. Defaults to 3 (h3)
• pop_count (integer) – How many popular downloads to show.  Default is 4.
• pop_cat_count (integer) – How many popular downloads to show per category. Default is 4.
• show_uncategorized (integer) – Set to 1 (default) to show an uncategorized section, or 0 to hide it.
• per_page (integer) – How many downloads to show per page. Default is 20.
• format – ID of custom format to use.
• exclude – Comma separated list of downloads to exclude from the listings.

So for example, to show 5 popular downloads I’d use:

[download_page pop_count="5"]

Easy peasy.

Customisation

So you want to customise the look? You can probably do that with CSS, either in your themes CSS file or by customising the styles.css which came with the plugin – this is found in download-monitor/page-addon/styles.css.

If for any reason the output looks unstyled completely, your version of wordpress may not support the way I added the styles.css file, so just paste the css code from that into your themes css file.

Configuring Download Data

The download page add-on is smart and uses your downloads custom fields to show the information. It lets you show an unlimited amount of custom fields like this:

1. You add custom fields to a download, for example, ‘licence’ with value ‘Free (GNU General Public License)’.
2. You then add a custom field called ‘include_fields’ and list the names of the fields to include on the download page separated by commas, e.g. tags,licence,wordpress-plugin-directory-page,documentation.

There are a few reserved custom field names you can use too:

• post_id = add an id of an associated post to the download – the read more link on the download page will link to this post.
• side_content = some content to show underneath the download link. On my site ive inserted some adsense code.
• thumbnail = path to an image for the download’s thumbnail. 112×112 is ideal for this.
• hide_download_button = Won’t show the download button. I’ve done this for my paid icon set because they cannot be downloaded from the site.
• hide_hits = Hide hit count

Finally, remember I did not have to release this add-on for free, so please consider making a donation to ensure I continue developing download monitor in the future.

Top