# Coppermine Photo Gallery v1.5.x: Documentation and Manual

# Uploading pics by FTP / Batch-Add Pictures

FTP-uploads plus batch-adding is the recommended method to upload files for the admin of a Coppermine-driven gallery. Only the admin can perform this for security reasons; non-admins can not perform this operation and need to use one of the other methods to upload files.

## What batch-add does

Coppermine is a database-driven app. This means that the files that get uploaded physically reside somewhere on the webspace. This could be any place - folder and file names for the files that get uploaded don't necessarilly have to be sorted in any particular way. The sorting and grouping is a matter of logic though: coppermine uses categories, sub-categories and albums to organize the display of files that were uploaded. To be able to do that, coppermine stores the physical location of the files (the paths that lead to your files) inside the database, as well as some other logical information (for example in which album a file resides).

When a file get's uploaded using your FTP app, Coppermine doesn't "know" where it is, so you have to tell the script the location to enable it to remember the location using the database. This is where the batch-add process comes into play. What the batch-add process does basically is: creating resized copies (thumbnails and intermediate images) of the original files you uploaded and then adding records into the database (one record per file you add) to be able to keep track where on the server's hard disk the file actually resides. With this being said it should be quite obvious: Coppermine doesn't move the files around - they remain where you uploaded them to in the first place.

That's why you should make up your mind in advance about the folder and file structure of your FTP uploads. They need to go into the albums folder, and it's advisable to create a clever structure of folders and sub-folders there.

It is recommended that the coppermine admin use ftp to upload multiple pics/files at a time. Use your ftp software to create sub-folders within your_coppermine_directory/albums/, where your ftp uploads can be saved. Though not mandatory, it's always a good idea to have a folder structure within the albums folder that reflects or mirrors your coppermine categories and albums.

Important: do not create folders or ftp upload to the userpics- nor to the edit-folder by ftp: these folders are used by coppermine internally and must not be used for any other purpose! Folder names must not contain dots. We also highly recommend refraining from the use of any other special characters - use only a-z, numbers and `-` (dashes) or `_` (underscores) to fill blank spaces. Make sure to upload in binary or auto-mode.

## How batch-add works

Once you have uploaded your photos by ftp, click on the "Batch Add Pictures" button. The batch-add is performed in three steps:

- find the directory under which you have uploaded your photos. Select this directory by clicking on it.
- select the photos you wish to upload (by ticking them). New pics are automatically pre-selected, those that already are in your coppermine database are not selected. Next select the album you wish to insert them into. Click "Insert Selected Pictures" to start the batch-add process.
- CPG will then display the results of the batch-add (allow some time for all results to display).
  If the OK, DP, or PB 'signs' does not appear, click on the broken file image to see if any error message was produced by PHP.
  Should your browser time out, hit the reload button.
  - : means that the file was successfully added
  - : means that the file is a duplicate and is already in the database
  - : means that the file could not be added, check your configuration and the permission of directories where the files are located
  - : means that you haven't selected an album the files should go to, hit 'back' and select an album. If you don't have an album create one first
  - : the file is broken or inacessible
  - : unknown file type
  - : the file is actually a GIF image and has just been renamed (e.g. to jpg or png)

Giving FTP-access to other users can pose a serious security threat, this is why batch-add is only available for the coppermine gallery admin.

Once files have been added to coppermine's database, make sure that you never rename or delete them via ftp - use coppermine's admin menu options to remove or rename files, instead. Only in this way will these files be removed from both the file system and the database.

## Common mistakes

There are some things that can go wrong when batch-adding, so here's a list to check first:

- Batch-add doesn't work as expected:
  - Make sure you have applied permissions on file system level
  - Toggle the interface: batch-add comes with two interfaces: the classic interface and the browsable interface. If you have issues with one, try the other
  - Avoid capitalization in folder and file names: coppermine can cope with capitalization, but it get's less likely that things don't work when using capitalization. That's why you should not use capitalization, i.e. all folders and files should be in lower-case
  - Avoid spaces in folder and file names. Spaces do not belong to the list of web-safe characters. Don't use them!
  - Don't use reserved file names: there is a number of prefixes that coppermine is using internally, so you shouldn't make sure not to use those reserved file names or prefixes. Don't use "thumb_", "normal_", "original_" in file names, as those are the default file prefixes
  - Don't use dots in folder names: files with leading dots are hidden files on most webserver operating systems, that's why it can be tricky to use dots. To be safe, do not use dots in folder names. Do not use leading dots in file names - in fact, file names should only contain one dot: the one that separates the file name from the file extension.
  If you have issues with batch-adding, make sure that http uploads work as expected first. If you want to request help on batch-add issues on the coppermine support board, please refer to the guide "Asking for support on upload issues" - it applies to batch-add issues just as well as any other upload method. Additionally to the suggestions made on that page, add a deep link pointing to one of the files that you're having issues with when batch-adding to your posting.
- Files appear to be broken: make sure that you have uploaded them using the proper FTP mode
- Do not rename files once they have been batch-added to coppermine's database. Of course, you mustn't rename the folders neither in which those files reside in
- Do not delete files using your FTP app after having added them to coppermine using batch-add. If you want to delete files, use the coppermine user interface to delete them.