• View
• Edit
• History
• Attach
• Print
• Backlinks

Attachtable

Questions answered by this recipe

• How can I rename attachments?
• How can I delete attachments?
• If I've deleted an attachment, how can I restore it or view it?
• How can I make (:attachlist:) look prettier and provide more information?

Description

By default, renaming or deleting attached files isn't possible from within PmWiki. This recipe adds that functionality, as well as an undelete action, and a modified list of attachments to provide easy links to using these actions. A few extra bells and whistles are also provided.

Screenshot using (:attachtable data=all:), see below for the CSS

To install this recipe

• download attachtable.phpΔ to your cookbook directory
• add the following line to your configuration file:

Usage

The directive (:attachtable:) accepts the same parameters as (:attachlist:) does, as well as some others, and generates a table rather than a list of attached files. It also has additional action links to delete ( ^X ) and rename/restore ( ^R ) files. Hover over the links for their tooltip explanations. These links are only visible if you have the required level of authorization (or have set otherwise, see below).

If you wish to use this recipe instead of the default attachment listing in the upload pages, edit the page Site.UploadQuickReference on your site and replace (:attachlist:) with (:attachtable:).

For full functionality, you'll need to have $EnableUploadVersions set on (not set by default). To do so, add the following to your configuration file before including attachtable.php:

By default, Attachtable actions require 'upload' authorization, except for deleting files from disk, which requires 'postattr' authorization. I picked 'postattr' because it's pretty much the highest level of authorization in a standard PmWiki. Authorization levels are customizable for all actions.

Deleting attachments - linked as ^X

If $EnableUploadVersions is set, deleting a file will first rename it to have a different extension (filename.ext,timestamp). Deleting such a "deleted" file will remove it from disk; this is confirmed using JavaScript, as it can't be undone.

Renaming & restoring attachments - linked as ^R

For the interactive prompt, you'll need to have JavaScript enabled (and not have $EnableAttachtableRename set to 0). If you have different size limits for different extensions, these will also be checked.

Viewing deleted files directly is also possible, with the proper MIME type and even if $EnableDirectDownload is set off.

Configuration

The following variables may be set in your config.php file to configure the way Attachtable works.

$EnableAttachtableRename

default: 0

Enables renaming of attachments

$EnableAttachtableLinkDeleted

default: 0

>Enables direct clickable link to deleted files

$AttachtableDataFields

default: array( 'size', 'modtime' )
The default data fields to display when not specified by a parameter to (:attachtable:). Valid entries are:

• 'size' - File size in bytes
• 'mimetype' - The MIME type of the file contents, if supported by your PHP engine
• 'modtime' - Time when file contents were last modified. Due to the way attachments are handled in PmWiki, this is synonymous with the time when this version of this file was uploaded.

The order of these fields matters, as it defines the order in which they're displayed.

$HandleAuth array entries

See the source code for the different $HandleAuth definitions and set them to override the default authorization levels, eg. with $HandleAuth['delattach'] = $HandleAuth['postattr'];
These also define the visibility of the action links in the attachtable.

$AttachtableFileCheck

Custom file check function, undefined by default, see below for more information.

(:attachtable:)

(:attachtable:) shows a tabular list of attachments of the current group or page, depending on whether attachments are organised per group or per page. It accepts the same optional parameters as (:attachlist:) as well as some additional ones:

(:attachtable NAME:)

Shows the attachments of the group or page NAME.

(:attachtable *:)

Shows the uploads directory and permits browsing of all uploaded files by directory if $EnableDirectDownload is not set to 0.

(:attachtable ext=xxx:)

Specifies an extension for filtering by type of file. To list multiple extensions, use ext='xt1 xt2' or ext=xt1,xt2. Attachtable's ext option will also list deleted files of the specified type, unlike (:attachlist:).

(:attachtable data=default|all|none|size|mimetype|modtime:)

Select which data fields to show in the table.

• Leaving this out or setting data=default will let $AttachtableDataFields determine the fields.
• data=all will show all fields (in the order size,mimetype,modtime).
• data=none only shows the file names.
• Any combination of the other three will show those fields in the order specified, eg. data=mimetype,size will show the file names, then the MIME type and third the file sizes.

(:attachtable actions=default|all|none:)

Show or hide the actions associated with the attachments.

• Leaving this out or setting actions=default will only show the actions that the user currently has permissions for.
• Setting actions=all won't circumvent the permissions required for the actions, it'll just show the links.
• actions=none will hide all the actions.

(:attachtable -titlerow:)

Hides the title row, which has explanations for the data columns.

(:attachtable -deleted:)

Hides deleted files.

Actions

If you'd rather use the actions directly, the format is as follows. For both, filename can already be marked as deleted.

?action=delattach&upname=filename

filename is deleted from disk or renamed to filename,timestamp, depending on $EnableUploadVersions and whether it's already marked as deleted

?action=renameattach&upname=filename&newname=newfilename

filename is renamed to newfilename

?action=downloaddeleted&upname=filename,timestamp

filename,timestamp, a deleted or overwritten file, is displayed with the correct MIME type

CSS

The above screenshot makes use of the following CSS to format the table:

.attachtable td { padding-right: 20px; }
.attachtable a { text-decoration: none; }
.attachtable a:hover { text-decoration: underline; }
.attachtable .del, .attachtable .del a { color: #cccccc; }
.attachtable .titlerow
	{
		color: #cccccc;
		font-style: italic;
		font-size: 0.8em;
	}

If you'd rather style it yourself, the table element has class='attachtable', the top row has class='titlerow' and deleted rows have class='del'. The action links have class='createlink'.

Notes

By default, Attachtable may relax your security settings slightly, as 'upload' access will now also grant read access to overwritten files, which access is not granted in a default PmWiki if $EnableDirectDownload is set to 0. If this is a concern, change the $HandleAuth definition for 'delattach' to whatever you need. 'postattr' access will also grant permission to delete attached files from disk when using Attachtable.

Attachtable's file restoration depends on PmWiki's versioning of overwritten files, where the file is renamed to "$filename,$Now" where $Now is a unix timestamp: an integer number of seconds since 1970. If you've changed some part of how PmWiki handles this, Attachtable may not work. Also important is the MakeUploadName function in upload.php, which by default strips commas from uploaded files and hence prevents naming uploads in a way that matches the pattern of a deleted file.

The rename/restore prompt and the deletion confirmation are done using JavaScript, but the actions themselves don't require it. Without JavaScript, the restore link will try to restore the file to its original name. Internet Explorer may prompt you for permission to open the prompt (though I can't understand why); there's very little I can do about this.

File verification when renaming files doesn't use the $UploadVerifyFunction function, but an internal function UploadVerifyRename that's based on the default UploadVerifyBasic function defined in upload.php.

Provided that $EnableDirectDownload is not set to 0, directories may show up in (:attachtable:) output, if using the * parameter or if directories exist in the uploads/NAME directory. Attachtable actions won't work on directories.

The file MIME types are found using a relatively robust process: first we try to use either mime_content_type or finfo_file; if these don't produce a decent result we try the shell command 'file -bi filename' and if that doesn't work we look up the extension in the $UploadExts array. I'm unable to test this on a non-Linux machine so I don't know if or how it'll fail in, say, a Windows server environment.

If you'd like to specify your own file check function, for example to implement a regular expression parser for filenames or to do more arcane things, you can specify a function and assign its name to the variable $AttachtableFileCheck. If such a function exists, it'll be called first to let it initialise any variables that it needs, then to check each file. You can use the following framework for defining the function:

$AttachtableFileCheck = 'MyFileCheck';
function MyFileCheck( $pagename, $file, $dir=FALSE, $opt=FALSE ) {
    // the use of the 'skip' parameter is completely optional
    ## $file is the file name
    ## defined only when initialising, $dir is the files' directory
    ## defined only when initialising, $opt is the ParseArgs output array
    static $skip = FALSE;
    if ($opt) {
        if ( @$opt['skip'] && ( $skip = $opt['skip'] ) ) { # note assignment
            // $skip here has the non-null string value that was passed to it 
            // using (:attachtable skip=...:)
        }
        // more initialisation code
    }

    if ( $skip && $file ) {
        // check that file is ok
    }

    return TRUE;
        // return indicates whether the file should (TRUE) 
        // or should not (FALSE) be listed
}

Features under consideration

• non-JavaScript file rename prompt
• remap links on wiki pages when renaming a file
• attachtable sorting
• internationalization
• PITS 00273 Refcount for attachments
• PITS 00331 display number of attachments for a page
• PITS 00659 enhanced Attach button

Release Notes

• 2007-11-28-2
  • external file check for Petko's skip
  • bugfix: -titlerow parameter now actually works
• 2007-11-28
  • MIME types
  • rearrange columns
  • view deleted files
  • properly read authorization levels for action link display
  • no $EnableUploadOverwrite dependency
• 2007-11-27
  • verify on rename
  • globals to disable parts
  • optional direct links to deleted files
  • handle directories better
• 2007-11-26
  • file rename action
  • internal reworking
  • simplify: more parameters & no globals
• 2007-11-25 - answering Petko's suggestions
  • by default, only show permitted actions
  • delete from disk
  • superscripted restore link
  • minor cleanup & bugfixes
• 2007-11-24 - first release

See Also

• PmWiki.UploadsAdmin
• PmWiki.UploadVariables
• Cookbook.AttachDelete An enhancement to the current upload feature to allow the deletion of uploaded files.
• Cookbook.FileList Tabulated filelist markup as alternative to (:attachlist:), for a simple, easy readable look.
• Cookbook.MultiUpload Upload multiple files at once by packing them in a zip archive & extracting them on the server
• PITS 00598 add possibility to delete attachments
• PITS 00665 Allow customization of attachlist output

Contributors

• EemeliAro

Comments

I'm open to suggestions for how to improve this. More specifically, I'd be interested to hear about the following: --EemeliAro November 25, 2007, at 04:58 PM

• What other information columns should there be?
• Is there a need for more fine-tuned control of the action links?
• Should the JavaScript prompts and confirmations be replaced by HTML pages?

# added after "if ( @$matchext &&..."
if(function_exists(@$AttachtableFileCheck)
   && !$AttachtableFileCheck($file, $opt) ) continue;
   $filelist[$file] = $file; # current line 266

This will allow me to write the checking function. --Petko November 27, 2007, at 08:09 PM

Done, see above and source code as it's slightly different from what you suggested. --EemeliAro November 28, 2007, at 05:31 AM

Thanks, it works for me (the "static" variable may interfere if there are two attachtables in a page). --Petko November 29, 2007, at 01:01 PM

It shouldn't, as each is processed in turn, and each gets initialised before looping through the files. Hence provided your $AttachtableFileCheck doesn't assume the static variable is FALSE if the property you're looking for isn't in the (:attachtable:) directive. --EemeliAro November 29, 2007, at 02:17 PM

I have now this idea of implementing a parameter like list= in pagelists, and an array similar to $SearchPatterns which admins can define. May be much better and flexible than skip=. This could be a lot of work, I don't know yet, so unless you like it a lot and are impatient, I'll write it in a couple of days. :-) --Petko November 29, 2007, at 01:01 PM

I've modified Attachtable to use UserAuth to support specific page and group auth access i.e. <action>_group/page. You can download it here: attachtable_userauth.phpΔ //Aidin

Nice recipe, but I have one Question: I've added this recipe to our project wiki (http://crrcsim.sourceforge.net/wiki), but deleting files doesn't work. I don't seem to have delattach permissions (action link not displayed, only upload and rename) even when I'm logged in as admin. The wiki does not use any advanced auth mechanisms (AuthUser, UserAuth, ...), just definitions for the $DefaultPasswords admin, upload and attr. How do I gain "postattr" permissions? The PmWiki docs say nothing about it. --Jan R

$HandleAuth['deldelattach'] = 'admin';
$HandleAuth['delattach'] = 'upload';
$HandleAuth['renameattach'] = 'upload';
include_once("$FarmD/cookbook/attachtable.php");

Thanks a lot, that solved all my problems! This is exactly what I wanted. --Jan R

How would one go about changing the display of filesize from bytes to KB, or even to MB? thanks!

overtones99 June 18, 2008, at 06:08 PM

	   //$s .= '<td>'.number_format($stat['size']).'</td>';   /// original this is where the byte size is created/calculated
	   $s .= '<td>'.bytesToNBytesFunc($stat['size']).'</td>';   /// *** call func to convert to KB

... and changed the code from the PHP site to make it "American" style (decimals instead of commas):

         /// from http://php.net/manual/en/function.number-format.php#72969
         function bytesToNBFunc($a) {
             $unim = array("B","KB","MB","GB","TB","PB");
             $c = 0;
             while ($a>=1024) {
                 $c++;
                 $a = $a/1024;
             }
             //return number_format($a,($c ? 2 : 0),",",".")." ".$unim[$c];
             return number_format($a,($c ? 1 : 0))." ".$unim[$c];  // using decimals instead of commas, 
                                                                        and only 1 decimal point...
         }

works great. thanks for the suggestion. overtones99 June 25, 2008, at 08:15 PM

Hi. How can I prevent attachtable from redirecting to the confirmation on Group.Page?action=upload..., and instead just go back to the page where I was uploading from (in this case, Group/Uploads)? Even better, I'd love to be able to have an options field like this:

 (:attachtable MyGroup.MyUploadPage
redirect=MyGroup.MyUploadPage#currentUploads:)

Is something like this possible? Thanks, overtones99 June 22, 2008, at 04:58 PM

        // *** Prevent confirmation page - Placed in both deleteattach and renameattach functions ***//
	//Redirect($pagename,"{\$PageUrl}?action=upload&uprname=$upname&upresult=$result");

	if(stristr($pagename,"Uploads")) { // skip uploads page, and redirect right back to page's uploads	
                // good if upload list is at the bottom of the page
		Redirect( $pagename, "{\$PageUrl}#currentUploads" ); 
	} else { // DEFAULT ACTION
		Redirect( $pagename, "{\$PageUrl}?action=upload&uprname=$upname&$result" ); // original redirect
	}

my only suggestion was that it my be nice to have a 'redirect' option where redirect=1 or by default uses the default confirmation page... and 'redirect=$PageUrl#currentUploads' goes to where you want after uploading

overtones99 June 25, 2008, at 09:27 PM

Brilliant! Great work, thanks so much for this recipe! /Elk