[[PageOutline(2-5, Contents, pullout)]]

= Adds a downloads section to Trac

== Description

This plugin provides a downloads section which may contain releases or other files. It is administrated via WebAdminPlugin and there is an interface to the {{{trac-admin}}} tool that may help during automatic server maintenance. The Downloads section of Trac displays a table with information about the uploaded files such as description, component, version, size, architecture, type and optionally assigned tags which the download is related to. It also collects information about the number of downloads which can be displayed on a wiki page together with direct links to the specified download. 

== Bugs/Feature Requests

Existing bugs and feature requests for !DownloadsPlugin are 
[report:9?COMPONENT=DownloadsPlugin here].

If you have any issues, create a 
[/newticket?component=DownloadsPlugin new ticket] but read BugReporting page first, please.

[[TicketQuery(component=DownloadsPlugin,group=type,format=progress)]]

== Download

Download the zipped source from [download:downloadsplugin here].

== Source

You can [http://trac-hacks.org/svn/downloadsplugin check out] !DownloadsPlugin using Subversion, or [source:downloadsplugin browse the source] with Trac.

== Dependencies

!DownloadsPlugin for Trac 0.10 depends on WebAdminPlugin, since many of the configuration options are available only on appropriate WebAdminPlugin's pages. On Trac 0.11 this is supported by Trac itself. Optionally !DownloadsPlugin uses TagsPlugin for tags support.

== Installation

After installing plugin's egg you can set up few configuration variables in the `trac.ini` file. Their default values are: 

{{{#!ini
[downloads]

title = Downloads
path = /var/lib/trac/downloads
ext = zip gz bz2 rar # For 0.10 and 0.11 branch.
ext = zip,gz,bz2,rar # For 0.12 branch.
additional_tags = author,component,version,architecture,platform,type # 0.12 branch only.
visible_fields = id file description size time count author tags component version \
  architecture platform type # For 0.10 and 0.11 branch.
visible_fields = id,file,description,size,time,count,author,tags,component,version, \
  architecture,platform,type # For 0.12 branch.
unique_filename = False
consoleadmin_user = anonymous # Branch 0.12 only.
}}}

Option values:
 * Variable {{{title}}} sets text of main navigation bar button. 
 * The {{{path}}} is the location where the uploaded downloads are stored. It has to be accessible for writing to web server. 
 * Setting {{{ext}}} variable restricts allowed extensions of uploaded files. 
 * If {{{unique_filename}}} is enabled, then the plugin checks if the file name of the download file is not already occupied by any other download file. 
 * {{{visible_fields}}} variable controls appearance of downloads table columns in Downloads section.
 * {{{consoleadmin_user}}} option serves for permission checks when listing, adding or removing downloads using {{{trac-admin}}}. This option is available only in 0.12 branch. 
 * Another option available only in 0.12 branch is {{{additional_tags}}} that configures from which fields the download tags should be also generated.

'''Note:''' {{{ext}}} and {{{visible_fields}}} options have changed to comma separated lists in 0.12 branch of the plugin.

If you run Trac in an environment which needs to enable plugins explicitly, add the following lines in the `trac.ini` file: 

{{{#!ini
[components]
tracdownloads.api.DownloadsApi = enabled
tracdownloads.core.DownloadsCore = enabled
tracdownloads.init.DownloadsInit = enabled
tracdownloads.timeline.DownloadsTimeline = enabled
tracdownloads.wiki.DownloadsWiki = enabled
tracdownloads.admin.DownloadsWebAdmin = enabled # Branch 0.10 and 0.11.
tracdownloads.webadmin.DownloadsWebAdmin = enabled # Branch 0.12 only.
tracdownloads.consoleadmin.DownloadsConsoleAdmin = enabled # Branch 0.12 only.
tracdownloads.core.DownloadsDownloads = enabled # Branch 0.12 only.
tracdownloads.tags.DownloadsTags = enabled # With TagsPlugin installed.
}}}

In 0.12 branch, the {{{DownloadsCore}}} component was split into the {{{DownloadsDownloads}}} component, which handles Downloads section of Trac, and the {{{DownloadsCore}}} component that serves file download requests and other core features. This means that you can disable the {{{DownloadsDownloads}}} component to hide Downloads section from users. {{{admin}}} module was renamed to {{{consoleadmin}}}.

The next step is to upgrade your Trac environment: 

{{{#!sh
trac-admin <path_to_environment> upgrade
}}}

'''Note:''' Some environments might not handle download of large files gracefully. Notably the fcgi wrapper may timeout. A possible work around, that also adds HTTP "Range:" header support, is telling Trac to use "X-Sendfile". This may require configuration of your HTTP server as well:
{{{#!ini
[trac]
use_xsendfile = True
}}}

== Permissions

!DownloadsPlugin defines three permissions: 
 1. {{{DOWNLOADS_VIEW}}} for normal users.
 1. {{{DOWNLOADS_ADD}}} and {{{DOWNLOADS_ADMIN}}} for people who upload and administrate downloads.     
 1. {{{DOWNLOADS_ADD}}} permission is implemented since the 0.12 branch and allows a user to upload downloads without access to the WebAdmin interface.

You can grant these permissions using these commands:

{{{#!sh
trac-admin <path_to_environment> permission add <user> DOWNLOADS_VIEW
trac-admin <path_to_environment> permission add <user> DOWNLOADS_ADD # Branch 0.12 only.
trac-admin <path_to_environment> permission add <user> DOWNLOADS_ADMIN
}}}

== Macros

There are few wiki macros available:

{{{
[download:<download_id> <text>] or
[download:<download_filename> <text>]
}}}

Displays link to download identified by ID {{{<download_id>}}} or filename {{{<download_filename>}}} with text {{{<text>}}}.

{{{
[[DownloadsCount(1)]]
[[DownloadsCount(1, 2, 3)]]
[[DownloadsCount(foo.zip)]]
[[DownloadsCount(1, foo.zip, bar.rar, 3)]]
[[DownloadsCount()]]
[[DownloadsCount(0)]]
}}}

Displays sum of number of downloads for downloads identified by comma separated list of IDs or filenames. If there is empty list or any zero (last two examples), sum of all number of downloads for all downloads is returned. Non-existing downloads silently counts as zero. Works with branch 0.12 only.

{{{
[[ListDownloads()]]
}}}

Displays same table that is displayed in Downloads section of the Trac on a wiki page. Works with branch 0.12 only.

== Inteface to `trac-admin`

There is the ability to list, insert or delete downloads from server's console/script with following commands:

{{{#!sh
trac-admin <path_to_environment> download list
trac-admin <path_to_environment> download add <path_to_file> description=<description> \
    author=<author> tags="<tag1> <tag2> ..." component=<component> version=<version> \
    architecture=<architecture> platform=<platform> type=<type>
trac-admin <path_to_environment> download remove <download_filename>
trac-admin <path_to_environment> download remove <download_id>
}}}

All download attributes of {{{download add}}} command are optional, only the file must be specified. {{{console_admin}}} {{{trac.ini}}} option must be set to any user who has permission to perform the appropriate action.

== Recent Changes

[[ChangeLog(downloadsplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:Blackhex] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''