Jax Upload Manager v1.5
Manual

O. General Information

Program and Author

Credits

I want to say a very big Thank You to all people who supported this and many other Open Source projects by their hints, translations, affectionate adaptions and links on their websites...

My personal credits go to:

I. Introduction

What is Jax Upload Manager? - What do I need it for?

Jax Upload Manager is a PHP class (programming module) for quick programming of an Upload Manager Form. This form enables you to upload files to and delete files from a specified directory on your webspace.

Features

Jax Upload Manager comes along with the following features:

• easy to use class
  
  
• multi-user support (a user can only overwrite or delete his own uploads)
  
  
• base dir selection
  user can choose from a list of base dirs for upload
  
  
• ability to run multiple upload managers using the same class
  
  
• modern "Look & Feel"
  fonts and colors are adaptable individually via Cascading Style Sheets (CSS) - there are some prepared CSS-templates
  
  
• support for multiple languages
  (templates for German, English, Polish)
  
  
• logging of any action
  
  
• detailed manual
  
  
• free! (GPL)

System Requirements

Jax Upload Manager was written in PHP 4, a server-side programming language that produces dynamical generated web pages! (If unsure, ask your web space provider for PHP support!)

License

Jax Upload Manager and its components are published under the conditions of the GPL - General Public License version 2 or later! The complete text of this license you find in the file gpl.txt (part of the packet), respectively on the website of Free Software Foundation under http://www.fsf.org/copyleft/gpl.html

This license allows you to use and copy this software freely as well as it enables you to develop improvements. Furthermore you are bound not to touch the copyright notes resp. to set a link to the original script (http://www.jtr.de/scripting/php/classes/upload manager )!

II. Interface

Interface Scheme

The class upload_manager owns the following variables and methods:

class upload_manager
{
  array $um_list[ $key ] 
     -> (string)   base_dir;
     -> (array)    alt_base_dirs[ $key ][ "base_dir" ]
                   alt_base_dirs[ $key ][ "description" ];
     -> (array)    files_for_upload [ $suffix ] = "icon.gif" | "";
     -> (string)   stylesheet;
     -> (string)   return_url;
     -> (string)   return_form_field;
     -> (string)   return_type;
     -> (long int) max_file_size;
     -> (string    logfile;
     -> (array)    memorized_files [ $filename ] = (true|false);
     -> (string)   files_memorize_func;
     -> (string)   files_remember_func;

  void upload_manager( $um_key, $um_user )

  void show();

  string textlink( string um_key, string link_title, string link_target );
  string piclink ( string um_key, sring link_title, 
                   string link_target, string pic_url );
}

The array $um_list contains all important configuration settings. key is an alphanumerical string that indicates what upload manager to use (if you want to use more than one upload manager). In this case the key is forwarded via the GET variable um_key and you can access each upload manager via "it's" url:

http://mydomain.tld/upload/jax_um.php?um_key=um0815

or

http://mydomain.tld/upload/jax_um.php?um_key=um_pictures

In this example case you have to write the following settings into the two arrays: $um_list[ "um0815" ] and $um_list["um_pictures"]...

Class properties:

...->base_dir
tells the class which directory to use for saving the uploaded files.

...->alt_base_dirs
if you want to give your user the choice between different directories (eg. files, photos, vidoes etc.) you can use this array! in this case for every base dir you have to create an containing of two variables:

->alt_base_dirs[ $key ]["base_dir"] = "...";

and

->alt_base_dirs[ $key ]["description"] = "...";

description is a short! description for the content behind the basedir. this description will be displayed instead of the base dir in a HTML selection list. See example.php for more details...

Note: if you don't set alt_base_dirs nothing happens! if you create this array it's first entry will overwrite the value of the "normal" ->base_dir property!

->stylesheet
tells the script what stylesheet to use

->return_url
tells the script to which URL to return if the upload manager is finished and was not called in a new window. If called in a new (popup) window the popup is closed automatically if pressed the exit button.

Note: if you don't set a return_url the script will find out it automatically.. (recommended!)

->return_form_field
tells the script in which form field to put the return value if pressed exit button.. (if upload manager is called in a seperate window)

->return_type
tells the script in which format it has to give back the the return value if pressed the exit button.. There are 3 alternatives indicated by the following constants:

->logfile
tells the script in what file to log actions. If you don't change this variable the script takes jum.log for default. All actions are logged in .csv format to this file.

->max_file_size
tells the script how big a file is allowed to be for upload. Note: The upper limit of this value is defined by the settings in php.ini config file.

->files_for_upload
this multi dimensional array contains an entry for every file extension that is allowed to be uploaded. Note: Important is only the array index not the value!

...->um_list["um0815"]["files_for_upload"][".txt"] = "ico_txt.gif";

and

...->um_list["um0815"]["files_for_upload"][".txt"] = "blah blah";

cause the same result.

The value (ico_txt.gif) shown in this example could be the icon file name for a graphical file manager (planned for a future release)...

->memorized_files
holds the internal list of the files uploaded by the current user.

->files_memorize_func
reference to a user defined function that is called after every upload. This function can be used to store content of file memory list into database or file..

->files_remember_func
reference to a user defined function that is called on every start. This function can be used to restore the content of the file memory list from a database or from a file..

Class's Constructor:

->upload_manager( um_key )
Constructor that initializes the upload manager. Important!

->show()
Initial Display function that shows the upload manager. Important!

Help Functions:

->textlink() and ->piclink()
these are help methods that generate the special hyperlink for opening the upload manager window.

textlink() generates a simple <a href="..">Text</a> hyperlink.

piclink() generates a hyperlink behind a folder picture you can use for better illustration.

III. Application

How to use the class

To include the upload manager class into your website you have to include the class file and to generate an instance of the class: (as shown in example.php)

	...
	require( "modules/upload_manager.class.php" );
	$my_upload_manager = new upload_manager( "um0815" );
	...

Then you have to set up the parameters:

	...
	// load structural information
	$my_upload_manager->um_list["um0815"]["base_dir"]   = "myuploads";
	$my_upload_manager->um_list["um0815"]["stylesheet"] = "styles/default.css";
	$my_upload_manager->um_list["um0815"]["return_url"] = 
       "$PHP_SELF?do=upload_routine"; 

	$my_upload_manager->um_list["um0815"]["return_form_field"] = 
       "file_selection.imageurl";

	$my_upload_manager->um_list["um0815"]["return_type"] = JUM_URL;

    // file types allowed for upload
    $my_upload_manager->
        um_list["um0815"]["files_for_upload"][".gif"] = "ico_gif.gif";
    $my_upload_manager->
        um_list["um0815"]["files_for_upload"][".pdf"] = "ico_pdf.gif";
    $my_upload_manager->
        um_list["um0815"]["files_for_upload"][".html"] = "ico_html.gif";
    $my_upload_manager->
        um_list["um0815"]["files_for_upload"][".htm"] = "ico_html.gif";
    $my_upload_manager->
        um_list["um0815"]["files_for_upload"][".txt"] = "ico_txt.gif";

    // maximum allowed file size 
    $my_upload_manager->um_list["um0815"]["max_file_size"] = 2097152;
	...

In this example um0815 is the key for accessing the upload manager. If you want to run an additional upload manager within the same script you simply have to generate an additional array associated to another key.

Finally you have to initialize the class.

	...
	// initialize class!
	$my_upload_manager->show();
	... 

From this programm point the script is alive and waiting for "it's own" GET parameter. Easiest way to generate a hyperlink that activates the Formmailer is to use the methods textlink() or piclink():

echo $my_upload_manager->
   piclink("um0815","UploadManager","_blank","images/folder.gif");

Another demo for this upload manager class you find in the package "Jax NewsPage v1.5+" for which the class was developed originally.

Handling Multiple Users

Jax Upload Manager implements a simple user managment. To avoid people from deleting or overwriting another ones uploads, Jax Upload Manager remembers which files a user has uploaded and allows the user only to delete his "own" files...

By default this memory list is limited to the current browser session. As soon the users closes the browser window he has no access to the files he uploaded as the script does not remember which files the user uploaded.

If nescessary the class can be extended easily to save this memory list permanently and remember at next login.

To tell the Upload manager the name of the current upload user you can initialize the class with a username e.g. supported by your main program's user management system.

$my_upload_manager = new upload_manager( "um0815", "vollhorst" );

In this example the class is used for the user "vollhorst".

At the beginning the class reads the content of the file memory list from the session variables and stores it in class variable memorized_files[ ]. For every filename in memory there is a corresponding entry in this variable, e.g:

$memorized_files[ "demo.txt" ] = true;

if you want to save this memory list permanently on every upload and restore on every start you can define your own save and restore-functions which are defined by the variables: files_memorize_func and files_remember_func:

function my_save_function()
{
...
}

$my_upload_manager->files_memorize_func = "my_save_function";
...

IV. Frequently Asked Questions (FAQs)

Where to get informations about updates and changes

1. On my website (http://www.jtr.de/scripting/php/classes/upload manager ) ;-)
   
   
2. Sign into "JtR News"-Newsletter! (http://www.jtr.de/scripting/php/newsletter/newsletter)

V. Known Bugs and Problems

Currently there are no known bugs...If you find some - just tell me!

VI. List of Changes (Change Log)

Changes in Version 1.5:

• multiple base dirs selectable
  now you can define several base dirs on each upload manager so that users can select an appropriate base dir from a HTML select box.
  

Changes in Version 1.4:

• check out return_url automatically
  now the module can find out the current URL and can automatically forward all GET parameters
  
  
• different types of return values
  allows to give back uploaded file location as "relative path" or absolute "url"

Changes in Version 1.3:

• multi user management
  now class supports different users
  

Changes in Version 1.2:

• multiple languages
  now class supports language localisation via template file
  
  
• returning selected file name
  now class returns the name of selected file if user presses exit
  
  
• logging
  all actions are logged into log file

If you have found any errors or if you have questions or suggestions for improvement then please don't hesitate to contact me directly!

Berlin, 3 Nov 2003 - Jack (tR)