This documentation is for the old version. Go to the latest Upload Suite docs

Uploading Folders

When users want to upload large amounts of images, it is often more convenient to allow them to upload whole folders. This topic contains basic instructions on setting up the client-side and server-side environment for this case.

Client Side

There are three properties in Image Uploader that are related to folder upload. The first one is ShowSubfolders which specifies whether subfolders are displayed in the folder pane. The second one, AllowFolderUpload, permits upload of files contained in the selected folders. And the last is IncludeSubfolders which specifies whether to upload files contained in subfolders recursively. Let us consider how these properties affect Image Uploader behavior in different layouts more detailed.

Showing Folders

As it was mentioned above, the property which determines whether to display subfolders is ShowSubfolders. If it is true, subfolders are shown in folder pane along with files. This property makes sense in two panes and three panes layout modes because ShowSubfolders affects folder pane only.

Whenever subfolders are displayed (ShowSubfolders property is set to true) the user can navigate to these subfolders double-clicking them.

Adding Folders

The way Image Uploader adds folders to the upload list depends on AllowFolderUpload and IncludeSubfolders properties. You can combine their values to obtain desired behavior.

The table below lists all possible combinations of AllowFolderUpload and IncludeSubfolders properties values and describes Image Uploader behavior in different layouts.

	AllowFolderUpload	IncludeSubfolders
One pane	`True`. Image Uploader adds the folder to the upload pane when the user chooses it in the Open Folder dialog or drags it from Windows Explorer.	`True`. Files contained in selected folder are uploaded along with subfolders ones. Additionally, the Include Subfolders checkbox in the Open Folder dialog appears checked.
		`False`. Only files contained in the selected folder are uploaded. Subfolders structure is not parsed. Additionally, the Include Subfolders checkbox in the Open Folder dialog appears cleared.
	`False`. Image Uploader adds files contained in the folder to the upload pane when the user chooses it in the Open Folder dialog or drags it from Windows Explorer.	`True`. Files contained in the selected folder are added to the upload pane along with subfolders ones. Additionally, the Include Subfolders checkbox in the Open Folder dialog appears checked.
		`False`. Only files contained in the selected folder are added to upload pane. Subfolders structure is not parsed. Additionally, the Include Subfolders checkbox in the Open Folder dialog appears clear.
Two panes	`True`. All the folders as well as files in folder pane have checkboxes. So to add a folder the user should select the checkbox on the icon of this folder.	`True`. Files contained in selected folder are uploaded along with subfolders ones.
		`False`. Only files contained in the selected folder are uploaded. Subfolders structure is not parsed.
	`False`. Folders have no checkboxes and cannot be selected for upload.	This property does not make sense if AllowFolderUpload is `False`.
Three panes	`True`. Image Uploader adds the folder to the upload pane when the user adds it using Add or Add All buttons or drags it from folder pane or Windows Explorer.	`True`. Files contained in selected folder are uploaded along with subfolders ones.
		`False`. Only files contained in the selected folder are uploaded. Subfolders structure is not parsed.
	`False`. Image Uploader adds files contained in the folder to the upload pane when the user adds it using Add or Add All buttons or drags it from folder pane or Windows Explorer.	`True`. Files contained in the selected folder are added to the upload pane along with subfolders ones.
		`False`. Only files contained in the selected folder are added to upload pane.

When the user adds a folder, independently of AllowFolderUpload property value, all Image Uploader limitations (like FileMask, etc) are applied to the content of this folder. If the folder contains too many files it will take long time to apply verification. A special dialog is displayed so the user is able to abort folder processing.

Note

A difference between the ActiveX version and the Java version is the following. In the ActiveX version, the dialog notifying that the folder is being processed appears in several seconds after the processing starts. In Java version, it appears at once.

Server Side

On the server side, you can receive the uploaded files, as usual. However, if you want to preserve a folder structure you need to slightly modify a common scenario.

In case of simple file upload, you usually:

Iterate through all uploaded files (their total number is received in the FileCount POST field).
If needed, in this loop read the name of each successive file from the FileName_i POST field, where i is the number of the successive file.
In the same loop iteration save the file using some pre-defined path value of your gallery.

When handling folder upload, you should modify the second and the third steps. The thing is if the AllowFolderUpload is true the FileName_i POST field contains not only the file name but also a relative path to the file. For example, if the user sends a MyDocuments folder, which contains a MyPhotos subfolder; all files inside this subfolder will be received on a server and their FileName_i POST fields will contain MyDocuments\MyPhotos\filename values.

As you see, parts of the path are separated with the back slash symbol (\). So, on Step 2, you need parse the path contained in the FileName_i POST field and create all the required folders under the gallery path. On Step 3 you need to append the relative path to the gallery path.

In pseudocode this may look as follows.

iterate through each file (i)
{
	//This value is taken from the FileName_i POST field
	string fullPath
	
	//This value is pre-defined
	string galleryPath
	
	//The 'split' function splits a string into an array of substrings using
	//the specified delimiter ('\' in our case)
	array folderStructure = split(fullPath, "\")
	
	//The 'goToFolder' function changes the current working folder to the
	//specified one
	goToFolder(galleryPath)
	
	iterate through each element of folderStructure (j)
	{
		//The 'exists' function checks if the specified folder exists under the
		//current location
		if not exists(folderStructure[j])
		{
			//The 'createFolder' function creates a subfolder
			createFolder(folderStructure[j])
		}
		goToFolder(folderStructure[j])
	}
	
	//The 'save' function saves the current file in the current working folder
	save(file[i])
}

Uploading Folders

Client Side

Showing Folders

Adding Folders

Server Side

See Also

Reference

Samples