modules/webfm/README.txt

// $Id$

Drupal webfm.module README.txt
==============================================================================

The Drupal webfm.module presents a paradigm shift in file management for Drupal.
This file manager is based on heirarchical directory structure unlike the
traditional flat filesystem used to date.  Webfm uses AJAX to allow users to
arrange files on the server in the same way they do with file managers on their
personal systems. This ability to heirarchically arrange files greatly
enhances the  managability of large collections of data.

WebFM does not exclude the use of the upload.module or other modules that depend
on the flat filesystem schema.  WebFM uses the file_move and file_copy functions
from file.inc.

Bug reports can be sent to the email address in the credits area below.


Installation
------------------------------------------------------------------------------

  - Unzip the archive and copy the 'webfm' directory to your modules directory
  (ie:/sites/all/modules). Alternatively copy the tarball to the module directory
  if you can unzip it on the server.

  - Enable the module on Drupal's admin/modules page.  An install file
  updates the database with the necessary table additions.


Configuration
------------------------------------------------------------------------------
Configure the module at admin/settings/webfm. Note: The configuration assumes
that the 'File system path:' is set in the usual way at admin/settings/file-system.
All WebFM directories are sub-directories of this 'File System' path. Set
'Download method:' radio to 'Public' since the module manages the download.

  - Create the 'WebFM root directory'. If this directory doesn't already exist,
  the system will create it in the 'File System' root. Multi directory root paths
  must already exist inside the 'File System' directory. Set the directory
  permissions to 775 if the server is linux/bsd.

  - The icon path allows the user to substitute their own gifs. File names are
  hardcoded in the javascript so the icons will have to have identical names.

  - The 'Maximum resolution for uploaded images' input functions in the same
  fashion as the root upload.module.

  - The 'Date Format' radio buttons set the day/month order in the browser
  listing date field.

  - The 'Display metadata title' checkbox sets the browser to display metadata
  titles rather than the actual filename if the metadata tile exists. Renaming
  files that use the metadata title must be done via the metadata editor.  Note
  that node attachments always display the metadata title if available.

  - 'Default File Permissions' set the file level permissions for files inserted
  into the database.  The exception is file uploads that create a version
  overwrite whereby the new file inherits the permissions from the previous file.

  - Roles that are granted the 'access webfm' permission will receive additional
  configuration fields for root path, extension white list, max upload file size
  and max total upload size. Roles with the 'access webfm' right but without a
  root directory cannot access the filesystem.

  - The 'WebFM attachments' section allows WebFM to attach files to nodes.
  'Attachment List Properties' sets the presentation of attached files.

  - The 'IE Drag-and-Drop Normalization' is a sub-optimal solution for
  compensating for relative positioning in theme css.  This feature is only
  available to #1 user.

  - The 'Webfm javascript debug' checkbox is only useful for users interested
  in looking under the covers or who want to develop the module.

  - The WebFM cron is a 'stored procedure' used for database cleanup of file
  records that are deleted outside of the WebFM interface (ie: OS shell, ftp).
  This feature is only available to #1 user.

Set WebFM rights in admin/user/access per role.

  - 'administer webfm' confers full rights to a role. Admins can see and operate
  on all files, including files not in the database. Only admins can create
  directories and access admin/settings/webfm.

  - 'access webfm' allows a role to download/view files via the WebFM browser.
  Only files referenced by the webfm_file table in the database are accessible.
  Only owners of a file (and admins) can move a file or modify it's metadata.

  - 'view webfm attachments' allows a role to see files attached to nodes via
  WebFM.

  - 'webfm upload' allows a role with the 'access webfm' right to upload files
  via the WebFM browser. The user who uploads a file is the the owner of that
  file.

Admins and File owners can set the following file level permissions:
  - Public download: Allows the file to be downloaded anonymously even if
    .htaccess exists.

  - Role View/Download: Allows users of the same role to view/download the file.

  - Role Attach: Allows users of the same role to attach the file to nodes.

  - Role Full Access: Allows users of the same role to delete/rename/move the
    file.  File permission edits are not allowed by role.

Enable attachments in admin/settings/content-types/*type* for each content type
that will accept attachments (default is disabled).

A .htaccess file (apache servers) can be placed in the WebFM root (or sub-path)
to secure file access. Webfm streams downloads and thus your browser doesn't
require direct http access to the directories

Updating the menu cache by navigating to admin/build/menu may be necessary if
upgrading from an earlier version of the module with different internal paths.

Translations of the module require revising the string array at the top of
webfm.js.


Features
------------------------------------------------------------------------------

  - Application-like look and feel via AJAX
  - Drag and drop moves of files and directories
  - Attachment of files to multiple nodes - location independence allows dir
    restructuring to have no affect on attachment functionality
  - Drag and drop attachment ordering
  - Single file upload with version options for file overwrite
  - File delete/rename/move/attach/metadata/permissions menu options for admins
    or file owners
  - File menu options for users with role access set by file permission
  - File store-in-db/remove-from-db admin menu options
  - Directory create/rename/delete admin menu options
  - Directory search for files that respects view privileges
  - Home directory per role with WebFM access
  - Secure file download if .htaccess file used
  - Metadata editor for admins or file owners(fixed fields at this time)
  - Debug window option for admin javascript development


Usage
------------------------------------------------------------------------------

There are many ways to setup a file system hierarchy. The rules of any given
system must be applied carefully if security of data is important.

The basic rules for users in a role with 'access webfm' rights:

    * The role root directory defines the domain and all subdirectories are
      accessible to the user.
    * The user cannot navigate above the role root directory.
    * Only files in the webfm_file table are accessible. Files uploaded by the
      user are owned by the user and are automatically in the database. Only
      module admins can view/operate on files not in the database.
    * The user has full control over files that he/she owns that stay within an
      accessible role root domain. File permissions can be locked down so that
      only the owner/admins can see or operate on a file. File permissions can
      be opened up so that anyone within the role can view or operate on the
      file.
    * Users with 'access webfm' rights cannot create/delete/move/rename
      directories. Only module administrators (users with 'administer webfm'
      permission or #1 user) can control the directory structure.

Roles with 'access webfm' rights can be subsets of other roles with 'access webfm'
rights or they can be exclusive. Users can be members of multiple roles and will
consequently have a separate left-hand tree for each unique root directory
(roles can even share the same root directory).

It is difficult to foresee how diverse users of the module will choose to set up
their systems but the following simple examples are typical arrangements. Both
examples presume that the drupal file-system directory is set to 'files', the
WebFM module is installed and the 'WebFM root directory' is set to 'webfm'.

Example 1
---------

The site requires 1 class of privileged users (A) to administer the file system
and 2 classes of WebFM users (B & C) with access to file resources. Both roles
will be able to upload files. Some WebFM users are members of both B & C while
others are members of only one. Uploaded files are by default only accessible by
the file owner and admins.

    * A site administrator will create 3 the roles A, B and C. Role A will have
      the 'administer webfm' permission set in .../admin/user/access. B & C will
      have the 'access webfm' and the 'webfm upload' permission set.
    * WebFM settings will now have a fieldset for roles B & C where the root
      directory for each role is set. The root of B is set to 'B' which
      automatically creates the 'files/webfm/B' directory. The root of C is set
      to 'C' which creates the directory 'files/webfm/C'. A user who is a member
      of only one of B or C will see a single left-hand directory tree that
      contains their domain. They will have no access to files within the other
      role domain. Users who are members of both B & C will have two left-hand
      directory trees and have the ability to move files they own or control
      between the two domains.

      Role A's root directory is the 'WebFM root directory' and thus A users see
      only a single left-hand tree of the entire module file-sys.
    * In WebFM settings, the 'Default File Permissions' are configured with all
      checkboxes unset. This combination of default file permissions means that
      files that are uploaded will initially only be viewable by the B or C user
      doing the upload (owner) and by A users. Individual file permissions are
      editable by the file owner or A user to permit other users to view/attach/
      modify the file. One consequence of granting the permission 'Role Full
      Access' is that a non-admin user with a single domain could lose contact
      with their own file if a dual domain non-admin user moves it to the other
      domain.

Example 2
---------

The site requires 1 class of privileged users (A) to administer the file system
and 2 classes of users (B & C) with access to file resources. C is determined to
be a subset of B such that B can access it's own files as well as those of C. C
will not be able to upload files to the browser but will only be able to view/
download  or attach files to nodes. B will be able to upload files.

    * A site administrator will create 3 the roles A, B and C. Role A will have
      the 'administer webfm' permission set in .../admin/user/access. B & C will
      have the 'access webfm' permission set. B will also have the 'webfm upload'
      permission set.
    * WebFM settings will now have a fieldset for roles B & C where the root
      directory for each role is set. First the root of B is set to 'B' which
      automatically creates the 'files/webfm/B' directory. Next the root of C is
      set to 'B/C' which creates the directory 'files/webfm/B/C'. Since C is a
      sub-dir of B, role B will have access to C but C will not be able to
      navigate above it's root to see B's files. The left-hand directory tree
      will appear different for B & C. B's tree will start at 'B' and have a 'C'
      sub-directory (and potentially other sub-directories as set up by A). C's
      tree is a subset of B's tree.

      Role A's root directory is the 'WebFM root directory'.
    * In WebFM settings, the 'Default File Permissions' are configured with
      'Role View Access' and 'Role Attach Access' set. This combination of file
      permissions means that files that a B user uploads/moves into the C realm
      will by default be viewable by C and be attachable to nodes that C creates.
      A B file owner can manually modify the file permissions of each individual
      file to hide it or prevent it from being attached to content by a C user.
      Likewise the file permissions can be opened so that a C user can edit file
      attributes or move the file into another sub-directory of C.

In the above examples the site administrator may simply create the roles/access
rules and then let an A user configure WebFM for B & C.


To Do
------------------------------------------------------------------------------

  - Flexible metadata scheme and standards based access for data mining
  - API for content/metadata search/sort.


Credits / Contact
------------------------------------------------------------------------------

(c) 2007 Web Community Resource Networks
401 Richmond St. W., Suite 384, Toronto, ON, Canada  M5V 3A8
http://web.net

Bug reports, feature requests, or other comments can be made on the project page
at http://drupal.org/project/webfm.

The author and maintainer of the module is Rob Milne.  Andre Molnar contibuted
db queries and php. Paul Shales assisted in the early development of attachment
and context menuing.

A lot of the php source is based on the Drupal upload module.

Sources for the javascript are to be found all over the web.  I borrowed ideas
from open source forums and modified to my needs.  The starting point was the
drupalization of the mxfb project on SourceForge.  Little residue remains of
that GPL code but it gave me much inspiration.  The event handler is based on
http://ajaxcookbook.org (Creative Commons Attribution 2.5 License).

I cannot remember where all the icon gifs originated but their provinence is
open source.
1	// $Id$
2
3	Drupal webfm.module README.txt
4	==============================================================================
5
6	The Drupal webfm.module presents a paradigm shift in file management for Drupal.
7	This file manager is based on heirarchical directory structure unlike the
8	traditional flat filesystem used to date. Webfm uses AJAX to allow users to
9	arrange files on the server in the same way they do with file managers on their
10	personal systems. This ability to heirarchically arrange files greatly
11	enhances the managability of large collections of data.
12
13	WebFM does not exclude the use of the upload.module or other modules that depend
14	on the flat filesystem schema. WebFM uses the file_move and file_copy functions
15	from file.inc.
16
17	Bug reports can be sent to the email address in the credits area below.
18
19
20	Installation
21	------------------------------------------------------------------------------
22
23	- Unzip the archive and copy the 'webfm' directory to your modules directory
24	(ie:/sites/all/modules). Alternatively copy the tarball to the module directory
25	if you can unzip it on the server.
26
27	- Enable the module on Drupal's admin/modules page. An install file
28	updates the database with the necessary table additions.
29
30
31	Configuration
32	------------------------------------------------------------------------------
33	Configure the module at admin/settings/webfm. Note: The configuration assumes
34	that the 'File system path:' is set in the usual way at admin/settings/file-system.
35	All WebFM directories are sub-directories of this 'File System' path. Set
36	'Download method:' radio to 'Public' since the module manages the download.
37
38	- Create the 'WebFM root directory'. If this directory doesn't already exist,
39	the system will create it in the 'File System' root. Multi directory root paths
40	must already exist inside the 'File System' directory. Set the directory
41	permissions to 775 if the server is linux/bsd.
42
43	- The icon path allows the user to substitute their own gifs. File names are
44	hardcoded in the javascript so the icons will have to have identical names.
45
46	- The 'Maximum resolution for uploaded images' input functions in the same
47	fashion as the root upload.module.
48
49	- The 'Date Format' radio buttons set the day/month order in the browser
50	listing date field.
51
52	- The 'Display metadata title' checkbox sets the browser to display metadata
53	titles rather than the actual filename if the metadata tile exists. Renaming
54	files that use the metadata title must be done via the metadata editor. Note
55	that node attachments always display the metadata title if available.
56
57	- 'Default File Permissions' set the file level permissions for files inserted
58	into the database. The exception is file uploads that create a version
59	overwrite whereby the new file inherits the permissions from the previous file.
60
61	- Roles that are granted the 'access webfm' permission will receive additional
62	configuration fields for root path, extension white list, max upload file size
63	and max total upload size. Roles with the 'access webfm' right but without a
64	root directory cannot access the filesystem.
65
66	- The 'WebFM attachments' section allows WebFM to attach files to nodes.
67	'Attachment List Properties' sets the presentation of attached files.
68
69	- The 'IE Drag-and-Drop Normalization' is a sub-optimal solution for
70	compensating for relative positioning in theme css. This feature is only
71	available to #1 user.
72
73	- The 'Webfm javascript debug' checkbox is only useful for users interested
74	in looking under the covers or who want to develop the module.
75
76	- The WebFM cron is a 'stored procedure' used for database cleanup of file
77	records that are deleted outside of the WebFM interface (ie: OS shell, ftp).
78	This feature is only available to #1 user.
79
80	Set WebFM rights in admin/user/access per role.
81
82	- 'administer webfm' confers full rights to a role. Admins can see and operate
83	on all files, including files not in the database. Only admins can create
84	directories and access admin/settings/webfm.
85
86	- 'access webfm' allows a role to download/view files via the WebFM browser.
87	Only files referenced by the webfm_file table in the database are accessible.
88	Only owners of a file (and admins) can move a file or modify it's metadata.
89
90	- 'view webfm attachments' allows a role to see files attached to nodes via
91	WebFM.
92
93	- 'webfm upload' allows a role with the 'access webfm' right to upload files
94	via the WebFM browser. The user who uploads a file is the the owner of that
95	file.
96
97	Admins and File owners can set the following file level permissions:
98	- Public download: Allows the file to be downloaded anonymously even if
99	.htaccess exists.
100
101	- Role View/Download: Allows users of the same role to view/download the file.
102
103	- Role Attach: Allows users of the same role to attach the file to nodes.
104
105	- Role Full Access: Allows users of the same role to delete/rename/move the
106	file. File permission edits are not allowed by role.
107
108	Enable attachments in admin/settings/content-types/type for each content type
109	that will accept attachments (default is disabled).
110
111	A .htaccess file (apache servers) can be placed in the WebFM root (or sub-path)
112	to secure file access. Webfm streams downloads and thus your browser doesn't
113	require direct http access to the directories
114
115	Updating the menu cache by navigating to admin/build/menu may be necessary if
116	upgrading from an earlier version of the module with different internal paths.
117
118	Translations of the module require revising the string array at the top of
119	webfm.js.
120
121
122	Features
123	------------------------------------------------------------------------------
124
125	- Application-like look and feel via AJAX
126	- Drag and drop moves of files and directories
127	- Attachment of files to multiple nodes - location independence allows dir
128	restructuring to have no affect on attachment functionality
129	- Drag and drop attachment ordering
130	- Single file upload with version options for file overwrite
131	- File delete/rename/move/attach/metadata/permissions menu options for admins
132	or file owners
133	- File menu options for users with role access set by file permission
134	- File store-in-db/remove-from-db admin menu options
135	- Directory create/rename/delete admin menu options
136	- Directory search for files that respects view privileges
137	- Home directory per role with WebFM access
138	- Secure file download if .htaccess file used
139	- Metadata editor for admins or file owners(fixed fields at this time)
140	- Debug window option for admin javascript development
141
142
143	Usage
144	------------------------------------------------------------------------------
145
146	There are many ways to setup a file system hierarchy. The rules of any given
147	system must be applied carefully if security of data is important.
148
149	The basic rules for users in a role with 'access webfm' rights:
150
151	* The role root directory defines the domain and all subdirectories are
152	accessible to the user.
153	* The user cannot navigate above the role root directory.
154	* Only files in the webfm_file table are accessible. Files uploaded by the
155	user are owned by the user and are automatically in the database. Only
156	module admins can view/operate on files not in the database.
157	* The user has full control over files that he/she owns that stay within an
158	accessible role root domain. File permissions can be locked down so that
159	only the owner/admins can see or operate on a file. File permissions can
160	be opened up so that anyone within the role can view or operate on the
161	file.
162	* Users with 'access webfm' rights cannot create/delete/move/rename
163	directories. Only module administrators (users with 'administer webfm'
164	permission or #1 user) can control the directory structure.
165
166	Roles with 'access webfm' rights can be subsets of other roles with 'access webfm'
167	rights or they can be exclusive. Users can be members of multiple roles and will
168	consequently have a separate left-hand tree for each unique root directory
169	(roles can even share the same root directory).
170
171	It is difficult to foresee how diverse users of the module will choose to set up
172	their systems but the following simple examples are typical arrangements. Both
173	examples presume that the drupal file-system directory is set to 'files', the
174	WebFM module is installed and the 'WebFM root directory' is set to 'webfm'.
175
176	Example 1
177	---------
178
179	The site requires 1 class of privileged users (A) to administer the file system
180	and 2 classes of WebFM users (B & C) with access to file resources. Both roles
181	will be able to upload files. Some WebFM users are members of both B & C while
182	others are members of only one. Uploaded files are by default only accessible by
183	the file owner and admins.
184
185	* A site administrator will create 3 the roles A, B and C. Role A will have
186	the 'administer webfm' permission set in .../admin/user/access. B & C will
187	have the 'access webfm' and the 'webfm upload' permission set.
188	* WebFM settings will now have a fieldset for roles B & C where the root
189	directory for each role is set. The root of B is set to 'B' which
190	automatically creates the 'files/webfm/B' directory. The root of C is set
191	to 'C' which creates the directory 'files/webfm/C'. A user who is a member
192	of only one of B or C will see a single left-hand directory tree that
193	contains their domain. They will have no access to files within the other
194	role domain. Users who are members of both B & C will have two left-hand
195	directory trees and have the ability to move files they own or control
196	between the two domains.
197
198	Role A's root directory is the 'WebFM root directory' and thus A users see
199	only a single left-hand tree of the entire module file-sys.
200	* In WebFM settings, the 'Default File Permissions' are configured with all
201	checkboxes unset. This combination of default file permissions means that
202	files that are uploaded will initially only be viewable by the B or C user
203	doing the upload (owner) and by A users. Individual file permissions are
204	editable by the file owner or A user to permit other users to view/attach/
205	modify the file. One consequence of granting the permission 'Role Full
206	Access' is that a non-admin user with a single domain could lose contact
207	with their own file if a dual domain non-admin user moves it to the other
208	domain.
209
210	Example 2
211	---------
212
213	The site requires 1 class of privileged users (A) to administer the file system
214	and 2 classes of users (B & C) with access to file resources. C is determined to
215	be a subset of B such that B can access it's own files as well as those of C. C
216	will not be able to upload files to the browser but will only be able to view/
217	download or attach files to nodes. B will be able to upload files.
218
219	* A site administrator will create 3 the roles A, B and C. Role A will have
220	the 'administer webfm' permission set in .../admin/user/access. B & C will
221	have the 'access webfm' permission set. B will also have the 'webfm upload'
222	permission set.
223	* WebFM settings will now have a fieldset for roles B & C where the root
224	directory for each role is set. First the root of B is set to 'B' which
225	automatically creates the 'files/webfm/B' directory. Next the root of C is
226	set to 'B/C' which creates the directory 'files/webfm/B/C'. Since C is a
227	sub-dir of B, role B will have access to C but C will not be able to
228	navigate above it's root to see B's files. The left-hand directory tree
229	will appear different for B & C. B's tree will start at 'B' and have a 'C'
230	sub-directory (and potentially other sub-directories as set up by A). C's
231	tree is a subset of B's tree.
232
233	Role A's root directory is the 'WebFM root directory'.
234	* In WebFM settings, the 'Default File Permissions' are configured with
235	'Role View Access' and 'Role Attach Access' set. This combination of file
236	permissions means that files that a B user uploads/moves into the C realm
237	will by default be viewable by C and be attachable to nodes that C creates.
238	A B file owner can manually modify the file permissions of each individual
239	file to hide it or prevent it from being attached to content by a C user.
240	Likewise the file permissions can be opened so that a C user can edit file
241	attributes or move the file into another sub-directory of C.
242
243	In the above examples the site administrator may simply create the roles/access
244	rules and then let an A user configure WebFM for B & C.
245
246
247	To Do
248	------------------------------------------------------------------------------
249
250	- Flexible metadata scheme and standards based access for data mining
251	- API for content/metadata search/sort.
252
253
254	Credits / Contact
255	------------------------------------------------------------------------------
256
257	(c) 2007 Web Community Resource Networks
258	401 Richmond St. W., Suite 384, Toronto, ON, Canada M5V 3A8
259	http://web.net
260
261	Bug reports, feature requests, or other comments can be made on the project page
262	at http://drupal.org/project/webfm.
263
264	The author and maintainer of the module is Rob Milne. Andre Molnar contibuted
265	db queries and php. Paul Shales assisted in the early development of attachment
266	and context menuing.
267
268	A lot of the php source is based on the Drupal upload module.
269
270	Sources for the javascript are to be found all over the web. I borrowed ideas
271	from open source forums and modified to my needs. The starting point was the
272	drupalization of the mxfb project on SourceForge. Little residue remains of
273	that GPL code but it gave me much inspiration. The event handler is based on
274	http://ajaxcookbook.org (Creative Commons Attribution 2.5 License).
275
276	I cannot remember where all the icon gifs originated but their provinence is
277	open source.