#format wiki
#language en
#pragma section-numbers off
#acl IanRiley:read,write,delete,revert,admin All:read,attach,detach
#pragma supplementation-page on

<<ContentsAndAppendices>>
= DropBox =

== Background and rationale ==

Attaching files to pages is a useful feature of MoinMoin, however to be able to upload files the user must have write privilege for the page.

In some circumstances it might be appropriate to allow users to attach and detach files without being able to edit the content of the page, for example when the page acts as a drop box.

== Description ==

The !DropBox action uses !AttachFile action as a core but allows the user to attach and detach files without having write access to the page. This requires the establishment of two additional access rights, Attach and Detach (see below).

As other MoinMoin actions, !DropBox can be called from the `More actions` menu or via the macro `<<Action(DropBox)>>`.

The page generated by !DropBox is similar to that of !AttachFile with the upload section first followed by the file listing.

The file listing starts with a summary of the things the user can do (sub-actions), such as upload, download and delete files.  The summary statements for various user ACLs are:

||'''User's ACL'''||'''Sub-action summary statement'''||
||read||'You can download, but not upload or delete files.'||
||read,attach||'You can upload and download, but not delete files.' ||
||read,attach,detach||'You can upload and download files, and delete your own files.'||
||read,write,attach,detach||'You can upload, download and delete files.'||

If `detach` without `read` and `attach`, then it is ignored. 

If `write` without `read`, `attach` and `detach`, then it is ignored. However, a user with `write` privilege can attach and delete files via the `AttachFile` action (assuming it is enabled).

!DropBox does not provide sub-actions to move, unzip or install files. Use !AttachFile action for these.

The file listing is either a single listing of all uploads, or two listings headed '''Your uploads''' and '''Other uploads'''.

The listing by default is sorted alphabetically on filename. This can be overridden to sort by file date, user who uploaded the file, file size or file type.

The listing is structure as:

filename - as a hyperlink to a view file action
sub-actions - del, get, view, depending on the user's ACL
datestamp - year and time
owner - as determined by the user who uploaded the file

See the examples below.

Following the listing further information on the files in the particular category is provided. This includes the number of files, the total size in kB and the date-time stamp of the most recent upload.

== Usage ==

Add the additional ACL rights in `multiconfig.py` and/or `config.py` as in the following examples.

In the options tuple.

{{{
'rights_default', u"Trusted:read,write,delete,attach,detach,revert Known:read,write,delete,attach,detach,revert All:read,write", "ACL used if no ACL is specified on the page"

'rights_valid', ['read', 'write', 'delete', 'attach', 'detach', 'revert', 'admin'], "Valid tokens for right sides of ACL entries."
}}}

In the !LocalConfig class.

{{{
acl_rights_default = u"IanRiley:read,write,delete,revert,attach,detach,admin"
}}}

Evoke from the "More actions" menu or the Action macro, for example:

{{{
<<Action(DropBox, "Upload/Download files")>>
}}}

<<Action(DropBox, "Upload/Download files")>>

!DropBox has two companion macros:

`<<UploadInfo>>`, inserts a summary the uploaded files, including number, total size and date-time of most recent upload.  See [[UploadInfo.py]] for more details.

`<<UploadList>>`, inserts a read-only upload file listing, as does the in-built `<<AttachList>>`, but in the !DropBox format.  See [[UploadList.py]] for more details.

If, as in the example below, anonymous uploads are allowed, it would be advisable that the user responsible for the drop box page subscribe for notification of new uploads. So if unwanted or overly large uploads are added, they can be promptly deleted.

== Download & Release Notes ==
|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:DropBox-1.2.py]] || 1.2 || 1.9.2  ||Added sort option  ||

== Examples ==

{{{
#format wiki
#language en
#pragma section-numbers off
#acl IanRiley:read,write,delete,attach,detach,revert,admin All:read,attach

= Ian Riley's example drop box =

== Add uploads ==

<<Action(DropBox,"DropBox uploads")>>

== Your uploads ==

<<UploadList(owners="Self")>>

== Other uploads ==

<<UploadList(owners="Other")>>

== Upload information summary ==

||Self||<<UploadInfo(owners="Self")>>||
||Other||<<UploadInfo(owners="Other")>>||
||All||<<UploadInfo>>||
}}}

The above renders:

||<tablesytle="width:100%">{{attachment:DropBoxExample1.png||width=100%}}||

The generated upload page:

||<tablesytle="width:100%">{{attachment:DropBoxExample2.png||width=100%}}||

== Copyright ==

 . @copyright: 2011 Ian Riley <ian@riley.asia>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * The owner of attachments are identified from userids in page's edit log, so this needs to be complete and provide the desired information for !DropBox to correctly categorise attachments. Perhaps it would be more robust if !AttachFile and !DropBox maintained a independent attachment log including ownership and other useful attributes.

-----

 Hits:: <<Hits>>