$Id: README.TXT,v 1.4 2006/00/07 18:39:17 dman Exp $

-- attach.module --
==============================================================================

Description
-----------
Enable EXISTING upload files or resources to be attached to nodes as if they 
had been uploaded.

This module enhances (and requires) the upload.module.

It adds a 'local filepath' entry next to the usual browse/upload widget. This 
field is integrated with the optional filebrowser.module to browse for the 
files.
Useful for migrating existing sites, file dumps, or dealing with content from
sources other than just attachment uploads.

Also provides 'save in' functionality to allow (or require) users to choose the
directory their uploaded files land in, or to put files in a location
corresponding to the path or their owner node. 

Entire directories can now be 'attached' to a node. With the filebrowser module,
a listing of that directory gets attached to a node display.


File Management 
---------------------------------------
Publishes a file attachment maintainence screen at "content >> manage files".
From there, an overview of all uploaded files displays some properties and links
to content nodes.
This directory browser is rooted from the systems 'files' directory. You will
want to check the 'administer attachments' AND 'access filebrowser' 
access control for this feature.

Save-As 
---------------------------------------
This module provides the ability to define the storage path for newly
uploaded files. A directory browser and autocomplete (provided by filebrowser)
make this easy.

When using 'save as' the target directory will, in the first instance, be
defined by the current nodes 'path'. If there is no path set yet, it will be
blank. Hitting 'preview' to set the path before uploading files will help

If a user does not have the 'Choose Upload Directory' right, they will only be
able to upload to /files/ as usual, OR a directory corresponding to the path
of the node. Only works when 'path' or 'pathauto' are being used.
To make this restriction work, for non-admin users, uploading is not possible
on brand new nodes - a node must be saved once to establish its path. 
Attachments can be made after that.

Options are found under access control.

Attach Directories 
---------------------------------------
Multiple nodes can now be associated with one file. In this case, viewing a node
displays the directory listing at the bottom of the page where the attachments 
table usually goes.

---------------------------------------
Requirements
---------------------------------------
This module requires Drupal 4.7.

It only starts working if upload.module is enabled.

It's only really powerful if filebrowser.module is updated and going.

If an updated version of filebrowser.module is available, the server filesystem
itself can be browsed to find the files. http://drupal.org/project/filebrowser
As of 7/7/2006 the patch for filebrowser.module is provided separate.

Installation
---------------------------------------
No tables, no special requirements, but the attach.install script should run to
 ensure that the WEIGHT of this module is greater than that of upload.module. 

Currently there are no settings and no settings page.
User access rights need testing.

The user must have rights to 'Upload Files'.
The ability to 'Attach Existing Files' must be enabled on top of that. 
Be aware this right grants browse privileges on all public directories.
The access right 'Choose Upload Directory' should be made available 
to appropriate users. 
Both Attach and Choose really only work well if the user has access to
filebrowsing. Enable that in the access control also.

History
---------------------------------------
Much of this was developed upon the framework of disknode.module by 
Michiel Hendriks < http://drupal.org/node/43600 > , however almost none of that
legacy now remains. The filenode browser was discarded in favour of the 
better-integrated filebrowser module, < http://drupal.org/project/filebrowser >
although I kept the shell of the template and CSS.

The code is trying to do just one thing, and avoided adding too many features 
or replacing work done before. Integrating with the established upload module 
(although a little too closely at points) was seen as better than branching in
any new directions.

Working behind the scenes to convince the upload.module to save files elsewhere
in the system was truly hairy. It eventually touches a few of the upload 
internals in ways it probably shouldn't.

TODO
---------------------------------------
Security, and possibly some finer control of what can be attached by who.
Currently publishes the entire files directory - this may not be always wanted.

Nested directories with the same name (files/files/ or private/private/) may 
occasionally confuse it, as the safety mechanism trims off the root folder name
to prevent exploits.

@author Dan Morrison < http://coders.co.nz/ >