File Manager Design Document

by Ron Henderson and Joshua Finkler

I. Essentials:

II. Introduction:

The ACS File Manager is a simple tool that allows content managers to work on a site even if they don't have access to the machine on which it runs via FTP or SSH login. Through the File Manager's Web-based user interface, text files can be edited using HTML forms and new versions of binary files - such as image files - can be uploaded, replacing prior versions. If your site uses version control, then File Manager will also take care of recording all changes in the version control system. In addition to editing existing files, content managers can also add new files to the system and create directories.

III. Historical Considerations

In order that the File Manager application integrate properly in a professional development environment, provisions had to be made to ensure that version control constraints be respected and file access permissions be configurable at a high degree of specificity.

IV. Competitive Analysis

The ACS File Manager is a lightweight content management tool. It provides the mimimal functionality necessary for non-programmers to work on a site. It's main limitations are fine-grain access control and access to the full revision history of an item.

V. Design tradeoffs

Keep in mind that all file operations (uploads, edits, creating directories, etc.) are executed by the running AOLserver process. This means that permissions are determined by the umask of the corresponding account, usually nsadmin. As a minor security check, File Manager does not allow file names with /'s, spaces or &'s, making it more difficult for users to create files outside of the server's pageroot.

VI. Data Model

The File Manager application has no data model.

VII. Legal transactions

The File Manager application has no data model and hence no legal transactions with the database.

VIII. API

File Manager is fully integrated with CVS (the version control system used by all ArsDigita development projects). All CVS transactions are handled by the version control application. If you want to use version control in conjuction with a remote repository, make sure you follow the instructions for setting up access to a remote repository.

IX. User Interface

The user interface looks like a file browser. It uses the following icons to indicate file status and type for various items under the server's pageroot:

Folder
Editable text file
Editable image file
Locked file, e.g. a file under version control with local modifications
Forbidden file that cannot be edited or uploaded using File Manager

You can click on text or image file icons to see a preview of the item, and you can click on file names to edit or upload new content. Clicking on a folder will navigate to that directory and display its contents. Forbidden files cannot be operated on.

X. Configuration parameters

The set of files and directories that content managers are allowed to work on can be configured in the parameters file. The following set of parameters control the behavior of File Manager:
[ns/server/yourservername/acs/file-manager]
EnabledP=1
; use version control?
VersionControlP=1
; extensions of files that be can edited/uploaded using File Manager
Extensions=html,adp,jpg,gif
; directories to ignore
Ignore=admin,CVS
; directories to manage (relative to www)
ManagedDirectories=acs-examples,ads,graphics

The VersionControlP flag controls whether the version control application should be used to record all changes to files. The Extensions parameter is a list of file extensions that correspond to editable files. The Ignore parameter lists directory names that should never appear in the file listing. The ManagedDirectories parameter controls which directories will be accessible via file-manager. If you leave this parameter out then all directories will be available.

XI. Acceptance tests

You should test adding and editing a file:

XII. Future Improvements/Areas of Likely Change

The ability to delete, rename, and move files and directories would be nice. It would also be nice to have a fixed set of permissions from which to choose when constraining file access for different user groups.

XIII. Authors: