modules/swfupload/README.txt

sfwupload Module
================================================================================

DESCRIPTION:
--------------------------------------------------------------------------------
The SWFUpload module replaces the default upload and handles the upload through 
javascript/flash. It depends on the SWFUpload library which makes it possible to 
upload multiple file at once. 

For developers the swfupload module provide a hook function. Using this hook 
function developers can access several tasks of the upload process.


INSTALLATION:
--------------------------------------------------------------------------------
1. Enable the upload module.

2. Download and the swfupload module.
     (http://drupal.org/project/swfupload)

3. Download the SWFUpload 2.2 release.
     (http://code.google.com/p/swfupload/downloads/list)

4. Copy the files 'swfupload.swf' and 'swfupload.js' to the swfupload folder 
   inside the module folder. The end result will read:
     modules/swfupload/swfupload/swfupload.js
     modules/swfupload/swfupload/swfupload.swf

5. Download and install the required jquery_plugin module 
     (http://drupal.org/project/jquery_plugin).

6. Download the jQuery plugin TableDnD and place it inside the jquery_plugin 
   module folder.
     (http://www.isocra.com/2008/02/table-drag-and-drop-jquery-plugin/)

7. Download the jQuery plugin cssPNGFix and place it inside the jquery_plugin 
   module folder.
     (http://plugins.jquery.com/project/cssPNGFix)

8. Enable this module by navigating to:
     admin/build/modules

9. Configure the swfupload settings by navigating to:
     admin/settings/swfuploads


USAGE:
--------------------------------------------------------------------------------
The swfupload module depends on the core upload module, but replaces its upload 
fieldset in node forms. To give users permissions for uploading and accessing 
navigate to admin/user/permissions#module-upload. This module also provides a 
settings page on which administrators can configure upload settings per node-
type and per user-role. 

Developers can take the advantage of the hook function hook_swfupload(). Using 
this function developers have access to alter the way the files are displayed,
as well as how file uploads are processed. 


API:
--------------------------------------------------------------------------------

FORM ELEMENT SFWUPLOAD

  DESCRIPTION:

  Format a swfupload button. All required scripts and styles are included when 
  this form element is used.

  PROPERTIES:

  #type, #default_value, #max_files, #filepath, #file_extensions, 
  #max_img_resolution, #max_file_size, #max_queue_size, #node_settings

  EXAMPLE:

    $form['swfattachments']['upload'] = array(
      '#type' => 'swfupload_button',
      '#default_value' => drupal_to_js($form['#node']->files),
      '#max_files' => $settings['max_files'],
      '#filepath' => $settings['filepath'],
      '#file_extensions' => $settings['file_extensions'],
      '#max_img_resolution' => $settings['max_img_resolution'],
      '#max_file_size' => $settings['max_file_size'], // The maximum bytes per file
      '#max_queue_size' => $settings['node_max_file_size'], // The maximum bytes in the queue
      '#node_settings' => $settings, // Used to pass the settings for the current node to hook_swfupload. 
    );


HOOK_SWFUPLOAD():

  DEFINITION:

  hook_swfupload(&$file, $op, &$instance)
  

  DESCRIPTION:

  Provide other modules a hook to change the data for the swfupload scripts.
  Modules can change the default provided fields, customize the way files are
  uploaded and change the type of swfupload (table or button).

  PARAMETERS:

  $file: The file object in its different states. 

  $op: What kind of action is being performed. Possible values:
    
    'init': The swfupload is being initialized. Here you can change the instance
            object in order to define other javascript callback functions, or to
            change the way the files are displayed.

    'move_uploaded_file': The swfupload requests an upload. Here you can alter 
            the file object in order to change it's filename or the destination
            folder. You can also change the validation functions which are passed 
            to file_save_upload(). The file object will look something similar 
            like this: 

            $file = (object) array(
              'validators' => array(
                'file_validate_extensions => 'jpg jpeg gif png txt',
                'file_validate_image_resolution' => '800x600',
                'file_validate_size' => array('1048576, 33554432),
              ),
              'filepath' => 'files/'
            );

    'upload_complete': The upload is complete. Using the hook_function in this 
            state, the file can be copied, modified or you can do some database 
            stuff. The file object will look something similar like this:

            $file = (object) array(
                'filename' => 'Image1.png',
                'filepath' => 'files/Image1_3.png',
                'filemime' => 'image/png',
                'source' => 'upload',
                'destination' => 'files/Image1_3.png',
                'filesize' => 220567,
                'uid' => '3',
                'status' => 0,
                'timestamp' => 1227182505,
                'fid' => '2468' }
              ),
              'filepath' => 'files/'
            );

  $instance: The instance object in its different states. When $op is 'init' the 
      instance can be altered in order to change the callback functions or to change
      the way the upload module displayes files. When $op is 'move_uploaded_file' or 
      'upload_complete', the instance object can be used as a reference.
      The reference object on init:

      // The type of the instance. Currently only table is supported
      $instance->type = 'table';

      // Javascript callback functions
      $instance->callbacks = array(
        'swfupload_loaded_handler' => 'ref.swfUploadLoaded',
        'file_queued_handler' => 'ref.fileQueued',
        'queue_complete_handler' => 'ref.queueComplete',
        'file_queue_error_handler' => 'ref.fileQueueError',
        'file_dialog_complete_handler' => 'ref.dialogComplete',
        'upload_success_handler' => 'ref.uploadSuccess',
        'upload_progress_handler' => 'ref.uploadProgress',
        'upload_error_handler' => 'ref.uploadError',
        'upload_complete_handler' => 'ref.uploadComplete',
        'init_complete_handler' => 'ref.initComplete',
      );

      // The elements array represents all elements which are displayed on added files.
      // Each element can be changed. Javascript will render the proper markup.
      $instance->elements = array(
        'drag' => array(
          'class' => 'drag first',
          'type' => 'drag',
          'colspan' => 3,
          'title' => t('Description'),
          'add_separator' => TRUE,
        ),
        'icon' => array(
          'type' => 'icon',
          'class' => 'icon',
        ),
        'description' => array(
          'type' => 'text',
          'default_value' => '{filename}',
          'class' => 'text title',
        ),
        'list' => array(
          'title' => t('List'),
          'type' => 'checkbox',
          'default_value' => $node_settings->list,
          'class' => 'checkbox',
          'contains_progressbar' => TRUE,
          'add_separator' => TRUE,
        ),
        'alt' => array(
          'title' => t('Alternate Text'),
          'type' => 'textarea',
          'default_value' => '{filename}',
          'class' => 'text',
          'contains_progressbar' => TRUE,
        ),
        'cancel' => array(
          'class' => 'last',
          'type' => 'cancel',
        ),
      );


  EXAMPLE:

  /**
   * Implementation of hook_swfupload().
   */
  function MODULENAME_swfupload(&$file, $op, &$instance) {
    switch ($op) {
      case 'init':
        // Add a custom callback function to be executed after the scripts have 
        // been initialized.
        $instance->callbacks['init_complete_handler'] = 'myCustomCallbackFunction';

        // Add a custom editabe tabledrawer. 
        $instance->elements['test'] => array(
          'class' => 'drag first', // The class for the td
          'type' => 'text', // An editable textfield will be added. Values will be saved!
          'colspan' => 2, // Colspan for this td
          'title' => t('Description'), // This will be used in the th
          'add_separator' => TRUE, // Whether or not to put a separator between the colums in the thead.
        );
        break;
      case 'move_uploaded_file':
        global $user;
        $file->filepath = "files/$user->uid/"; // Files will be stored in an user folder
        break;
      case 'upload_complete':
        db_query("INSERT INTO {mymoduletable} (fid, filename) VALUES ('%s', '%s')", $file->fid, $file->filename);
        break;
    }
  }


BUGS:
--------------------------------------------------------------------------------

1. If the swfupload is loaded inside a collapsed fieldset, Firefox occasionally 
   crashes when the fieldset expanded. 

2. If the 2.1 version of the SWFUpload library is used, Flash player 10 will not
   allow javascript to let flash open the file select window.

3. There will be more......


TODO:
--------------------------------------------------------------------------------

1. Add a new instance type called 'button'. Currently there's only an instance 
   type 'table' which displays the files in a list. With type set to 'button' 
   users can upload only images which replace the upload button.  

2. A lot of debugging.

1	sfwupload Module
2	================================================================================
3
4	DESCRIPTION:
5	--------------------------------------------------------------------------------
6	The SWFUpload module replaces the default upload and handles the upload through
7	javascript/flash. It depends on the SWFUpload library which makes it possible to
8	upload multiple file at once.
9
10	For developers the swfupload module provide a hook function. Using this hook
11	function developers can access several tasks of the upload process.
12
13
14	INSTALLATION:
15	--------------------------------------------------------------------------------
16	1. Enable the upload module.
17
18	2. Download and the swfupload module.
19	(http://drupal.org/project/swfupload)
20
21	3. Download the SWFUpload 2.2 release.
22	(http://code.google.com/p/swfupload/downloads/list)
23
24	4. Copy the files 'swfupload.swf' and 'swfupload.js' to the swfupload folder
25	inside the module folder. The end result will read:
26	modules/swfupload/swfupload/swfupload.js
27	modules/swfupload/swfupload/swfupload.swf
28
29	5. Download and install the required jquery_plugin module
30	(http://drupal.org/project/jquery_plugin).
31
32	6. Download the jQuery plugin TableDnD and place it inside the jquery_plugin
33	module folder.
34	(http://www.isocra.com/2008/02/table-drag-and-drop-jquery-plugin/)
35
36	7. Download the jQuery plugin cssPNGFix and place it inside the jquery_plugin
37	module folder.
38	(http://plugins.jquery.com/project/cssPNGFix)
39
40	8. Enable this module by navigating to:
41	admin/build/modules
42
43	9. Configure the swfupload settings by navigating to:
44	admin/settings/swfuploads
45
46
47	USAGE:
48	--------------------------------------------------------------------------------
49	The swfupload module depends on the core upload module, but replaces its upload
50	fieldset in node forms. To give users permissions for uploading and accessing
51	navigate to admin/user/permissions#module-upload. This module also provides a
52	settings page on which administrators can configure upload settings per node-
53	type and per user-role.
54
55	Developers can take the advantage of the hook function hook_swfupload(). Using
56	this function developers have access to alter the way the files are displayed,
57	as well as how file uploads are processed.
58
59
60	API:
61	--------------------------------------------------------------------------------
62
63	FORM ELEMENT SFWUPLOAD
64
65	DESCRIPTION:
66
67	Format a swfupload button. All required scripts and styles are included when
68	this form element is used.
69
70	PROPERTIES:
71
72	#type, #default_value, #max_files, #filepath, #file_extensions,
73	#max_img_resolution, #max_file_size, #max_queue_size, #node_settings
74
75	EXAMPLE:
76
77	$form['swfattachments']['upload'] = array(
78	'#type' => 'swfupload_button',
79	'#default_value' => drupal_to_js($form['#node']->files),
80	'#max_files' => $settings['max_files'],
81	'#filepath' => $settings['filepath'],
82	'#file_extensions' => $settings['file_extensions'],
83	'#max_img_resolution' => $settings['max_img_resolution'],
84	'#max_file_size' => $settings['max_file_size'], // The maximum bytes per file
85	'#max_queue_size' => $settings['node_max_file_size'], // The maximum bytes in the queue
86	'#node_settings' => $settings, // Used to pass the settings for the current node to hook_swfupload.
87	);
88
89
90	HOOK_SWFUPLOAD():
91
92	DEFINITION:
93
94	hook_swfupload(&$file, $op, &$instance)
95
96
97	DESCRIPTION:
98
99	Provide other modules a hook to change the data for the swfupload scripts.
100	Modules can change the default provided fields, customize the way files are
101	uploaded and change the type of swfupload (table or button).
102
103	PARAMETERS:
104
105	$file: The file object in its different states.
106
107	$op: What kind of action is being performed. Possible values:
108
109	'init': The swfupload is being initialized. Here you can change the instance
110	object in order to define other javascript callback functions, or to
111	change the way the files are displayed.
112
113	'move_uploaded_file': The swfupload requests an upload. Here you can alter
114	the file object in order to change it's filename or the destination
115	folder. You can also change the validation functions which are passed
116	to file_save_upload(). The file object will look something similar
117	like this:
118
119	$file = (object) array(
120	'validators' => array(
121	'file_validate_extensions => 'jpg jpeg gif png txt',
122	'file_validate_image_resolution' => '800x600',
123	'file_validate_size' => array('1048576, 33554432),
124	),
125	'filepath' => 'files/'
126	);
127
128	'upload_complete': The upload is complete. Using the hook_function in this
129	state, the file can be copied, modified or you can do some database
130	stuff. The file object will look something similar like this:
131
132	$file = (object) array(
133	'filename' => 'Image1.png',
134	'filepath' => 'files/Image1_3.png',
135	'filemime' => 'image/png',
136	'source' => 'upload',
137	'destination' => 'files/Image1_3.png',
138	'filesize' => 220567,
139	'uid' => '3',
140	'status' => 0,
141	'timestamp' => 1227182505,
142	'fid' => '2468' }
143	),
144	'filepath' => 'files/'
145	);
146
147	$instance: The instance object in its different states. When $op is 'init' the
148	instance can be altered in order to change the callback functions or to change
149	the way the upload module displayes files. When $op is 'move_uploaded_file' or
150	'upload_complete', the instance object can be used as a reference.
151	The reference object on init:
152
153	// The type of the instance. Currently only table is supported
154	$instance->type = 'table';
155
156	// Javascript callback functions
157	$instance->callbacks = array(
158	'swfupload_loaded_handler' => 'ref.swfUploadLoaded',
159	'file_queued_handler' => 'ref.fileQueued',
160	'queue_complete_handler' => 'ref.queueComplete',
161	'file_queue_error_handler' => 'ref.fileQueueError',
162	'file_dialog_complete_handler' => 'ref.dialogComplete',
163	'upload_success_handler' => 'ref.uploadSuccess',
164	'upload_progress_handler' => 'ref.uploadProgress',
165	'upload_error_handler' => 'ref.uploadError',
166	'upload_complete_handler' => 'ref.uploadComplete',
167	'init_complete_handler' => 'ref.initComplete',
168	);
169
170	// The elements array represents all elements which are displayed on added files.
171	// Each element can be changed. Javascript will render the proper markup.
172	$instance->elements = array(
173	'drag' => array(
174	'class' => 'drag first',
175	'type' => 'drag',
176	'colspan' => 3,
177	'title' => t('Description'),
178	'add_separator' => TRUE,
179	),
180	'icon' => array(
181	'type' => 'icon',
182	'class' => 'icon',
183	),
184	'description' => array(
185	'type' => 'text',
186	'default_value' => '{filename}',
187	'class' => 'text title',
188	),
189	'list' => array(
190	'title' => t('List'),
191	'type' => 'checkbox',
192	'default_value' => $node_settings->list,
193	'class' => 'checkbox',
194	'contains_progressbar' => TRUE,
195	'add_separator' => TRUE,
196	),
197	'alt' => array(
198	'title' => t('Alternate Text'),
199	'type' => 'textarea',
200	'default_value' => '{filename}',
201	'class' => 'text',
202	'contains_progressbar' => TRUE,
203	),
204	'cancel' => array(
205	'class' => 'last',
206	'type' => 'cancel',
207	),
208	);
209
210
211	EXAMPLE:
212
213	/**
214	* Implementation of hook_swfupload().
215	*/
216	function MODULENAME_swfupload(&$file, $op, &$instance) {
217	switch ($op) {
218	case 'init':
219	// Add a custom callback function to be executed after the scripts have
220	// been initialized.
221	$instance->callbacks['init_complete_handler'] = 'myCustomCallbackFunction';
222
223	// Add a custom editabe tabledrawer.
224	$instance->elements['test'] => array(
225	'class' => 'drag first', // The class for the td
226	'type' => 'text', // An editable textfield will be added. Values will be saved!
227	'colspan' => 2, // Colspan for this td
228	'title' => t('Description'), // This will be used in the th
229	'add_separator' => TRUE, // Whether or not to put a separator between the colums in the thead.
230	);
231	break;
232	case 'move_uploaded_file':
233	global $user;
234	$file->filepath = "files/$user->uid/"; // Files will be stored in an user folder
235	break;
236	case 'upload_complete':
237	db_query("INSERT INTO {mymoduletable} (fid, filename) VALUES ('%s', '%s')", $file->fid, $file->filename);
238	break;
239	}
240	}
241
242
243	BUGS:
244	--------------------------------------------------------------------------------
245
246	1. If the swfupload is loaded inside a collapsed fieldset, Firefox occasionally
247	crashes when the fieldset expanded.
248
249	2. If the 2.1 version of the SWFUpload library is used, Flash player 10 will not
250	allow javascript to let flash open the file select window.
251
252	3. There will be more......
253
254
255	TODO:
256	--------------------------------------------------------------------------------
257
258	1. Add a new instance type called 'button'. Currently there's only an instance
259	type 'table' which displays the files in a list. With type set to 'button'
260	users can upload only images which replace the upload button.
261
262	2. A lot of debugging.
263