[Pmwiki-users] File upload feature discussion

[Patrick R. Michaud]

Greetings, pmwiki-users!  This is likely to be a longish sort of message
to outline current thoughts on a "file upload" feature for PmWiki and
to solicit further feedback and suggestions.  We originally tried
discussing this via the wiki itself, and in the process we rediscovered
that wiki doesn't always work well for threaded conversations.  As a result,
several of us decided that it might be better and more timely to hold
development discussions (that have lots of points/counterpoints) via the 
mailing list instead of the wiki. 

As the discussion progresses I'll try to maintain a wiki page on 
pmichaud.com to keep track of the status of the discussion.

First, background:  One of the features that is most requested for PmWiki
is to have some convenient way for users to upload files that can be easily
embedded or accessed from within wiki pages.  There are a couple of
motivations for this:
  1.  Many people like wiki because they can easily create web pages
      without having to know HTML or about transferring files to a
      web server.  However, in order to make a graphic image or
      other resource available from a wiki page, it must first be placed
      on a web server somewhere, which makes things difficult for users
      who don't understand things such as file transfers, uniform resource
      locators, server directories, etc.
  2.  Even for those who do understand files and web servers, it would
      often make more sense to have these additional files and resources
      stored in a shared central location (much like the wiki pages
      themselves are a shared, central resource).

On the various wikis that I administer, the question of "how to I make
a file available in the wiki" repeatedly comes up.  Thus it seems that
this a feature that has enough demand and usefulness to warrant inclusion
in PmWiki.

I see two basic approaches available for associating files with wiki pages.
The first approach would be to simply create a file upload area, and 
locate or develop some scripts that allow people to upload and manage
the files in that area.  The PmWiki InterMap facility could then be
used to refer to the files in the upload area; for example, on several
of my sites I have set up a "WikiPub" InterMap alias that corresponds to
a centralized "resource" directory for that server.

The advantages of this approach are:
  - It's very easy to set up--just find and install a good web-based
    file management tool, and create a PmWiki InterMap entry to facilitate
    links to the files in the upload area
  - there are many web-based file management utilities in existence; see,
    for example, PhpCommander from http://www.szewo.com/php/commander/eng
    (I just found this via a Google search and know nothing about it)
  - It keeps the implementation of PmWiki quite simple
  - Site administrators can choose a file management utility that meets
    their specific needs and preferences 

However, after brainstorming on this for a while and seeing some comments
on other wiki systems, there are some potential disadvantages:
  - It's very easy for the file upload area to become "cluttered" and
    disorganized since there is little structure
  - It may be difficult to determine which files are "active" and 
    which are "leftovers".
  - Lack of structure may also promote abuse of the feature to
    store files not associated with the wiki (e.g., warez sites).
  - The overall file upload feature may not integrate well with PmWiki;
    e.g., it may be difficult to make it work within PmWiki's authorization/
    security model
  - It might be nice for there to be a "standard" PmWiki way of doing it

As a result, some wikis and some who have discussed this previously
advocate a slightly different approach, whereby the upload files and
resources are directly associated with ("attached to") specific pages
in the wiki system.  Put another way, any page in the wiki could have
some "attached file resources" which are managed within PmWiki.
This approach may overcome some of the potential disadvantages of the
first approach--namely:
  - Structure is automatically imposed on the uploaded files by the
    wiki pages
  - Security can potentially be enforced via PmWiki's existing 
    authorization mechanisms
  - The upload feature is likely to integrate more seamlessly
  - It's easier to keep track of the files within the file upload
    area itself

But, this second approach may have its own set of downsides:
  - It will likely make some parts of the PmWiki system more 
    difficult for site administrators to "customize"
  - The file management routines will likely have to be developed
    "from scratch", and these routines will have to pay special attention
    to web security issues
  - It substantially increases the complexity of the PmWiki software itself
  - It tends to force wiki administrators into a specific model of managing
    file uploads

So, I see arguments both for and against either approach.  I've actually
been thinking about some of these items for many months, but haven't
really made much progress.  So, I could really use some opinions and
reactions from all of you.

Of course, there's nothing that says the approaches have to be
mutually exclusive--we could certainly develop a system using one
approach and a site administrator could customize PmWiki to use a
different model if that's better for him/her.  But I know that whatever
ends up being distributed with PmWiki is likely to become the "standard",
so it's good to get it close to right the first time.

Also, I need to reiterate that it's the *design* issues that have been
hampering my progress in this area, not implementation ones.  Once I have
a design I'm comfortable with, I'm sure I'll be able to implement it 
without much difficulty.  Thus, I don't really need suggestions such as 
"you can create a directory on the server for each wiki page" and "use
XXX for the filenames".  What I do need is information about how the
file upload system ought to look to different PmWiki audiences.  For 
example, I need help with:
  1.  How the feature should look to the "wiki user"--the person who is
      creating web pages and uploading files.  In particular, this includes
	- What model are we taking for file/resource uploads, is it an
	  "upload pool" or do we go with "page attachments", "group files",
	  or something else entirely?
	- What wiki markup should be used to refer to uploaded resources
	  within a wiki page?
	- What actions does a wiki user take to initiate a file upload?
	- What file operations is a wiki user empowered to perform or
	  restricted from performing?
	- What is the look and feel of the file management interface?
	- How does a wiki user (author or reader) learn about the 
	  uploaded resources available?
  2.  How the feature should look to the "wiki administrator"--the
      person who has installed and possibly customized PmWiki.  This 
      includes questions such as:
        - What security and authorization features are needed?
	- How much flexibility does the administrator need in changing
	  the appearance of the file upload/file management features?
	- What sorts of site-wide file maintenance functions are needed?

And, a few initial "position statements" about where I stand on a few items
related to a file upload feature:
  - I'm not wanting to do anything that requires adding substantial amounts 
    of JavaScript or funky dynamic HTML programming to PmWiki, because there
    are just too many browser issues to be dealt with there.
  - I want to focus on simple mechanisms to do the basic "upload"
    and "delete" operations, and avoid things like "display directory
    trees" and "create subfolders" and "file icons".  These latter
    operations tend to create more difficult security issues and can be
    difficult to make work across multiple browser platforms.
  - I will be constantly using the PmWikiPhilosophy as a guide for
    implementation of this feature; especially items #3 and #4
    (avoid gratuitous features, implement things in response to specific needs,
    and allow PmWiki to be used/customized for web site maintenances).

Any comments or suggestions that any of you can provide will be greatly
appreciated.  Sometimes I just need people to "argue against" in order
to discover how I think something should work, and there will be times when
I'll take a devil's advocate position just to make sure all the bases are
covered.  It's unlikely that whatever gets created will meet everyone's
wish list, but hopefully we can get the basic needs taken care of while
leaving room for future expansion and customization on this feature.

So, with that background as an introduction, I'll restart the file-upload
conversation with a question:  Which of the following basic approaches 
should we take in the design of a file upload feature for PmWiki?
  1.  Have a centralized "upload file area" that uses InterMap links
  2.  Have files attached to individual wiki pages
  3.  Have files attached to wiki groups
  4.  Some other approach I haven't mentioned here

I'm very much looking forward to hearing all of your opinions.  :-)

Pm