# 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 does not work as expected:

  - #### Permissions

    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

  - #### Capitalization

    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

  - #### Spaces

    Avoid spaces in folder and file names. Spaces do not belong to the list of web-safe characters. Don't use them!

  - #### Special chars

    File systems used in computing have been invented with latin characters only in mind. The internet and the naming scheme it uses has been invented with latin-only characters in mind. Much later developers realized their mistake and tried to allow other characters as well, but then it was too late: the technology and standards used on the web are pretty old and therefore they work best if you only use latin characters (a to z) and numbers. Special characters (like Umlauts, accented characters or characters from non-latin alphabets) do not belong to the list of web-safe characters. Don't use them!

  - #### Forbidden chars

    There is a config field in coppermine that let's you populate a list of characters that are forbidden in file names. It's advisable not to change them (or at least not remove the characters that reside in that list out of the box), as those characters have got a special meaning. Of course you should not use those forbidden characters in folder or file names.

  - #### Reserved names

    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

  - #### Dots

    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.

  #### Asking for support on issues with batch-add

  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

  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

  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.
  Some users mistakenly thought that they could delete files once the batch-add process was done: that is not the case - all that batch-add does is creating the resized images (intermediate/thumb/watermark) and add a record to the database that corresponds to the file. You can not delete the file afterwards to save space. If you delete the file, you will get a broken record, which is very bad.

## Sorting

The Default sort order for files can be set in coppermine's config. Out of the box, it is set to "Name ascending", which simply is the best option for most and should therefore be preserved. Subsequently, all files that you upload using coppermine's built-in batch-add function will be sorted within the album they went into by filename. It's recommended to come up with a naming scheme for the files (that you have to apply to the files before uploading them from your client to the server) that takes into account the way the server operating file will sort the files.

Keep in mind that:

- ### Capitalization matters

  On most webservers there is a Unix-/Linux-driven operating system. Unlike Windows-driven operating systems, capitalization matters for sorting aspects. That's why files may be sorted in a "funny" way if you come from a Windows-driven background.

- ### Computers see numbers differently

  Computers (and the webserver your gallery runs on is a computer) perceive a list of numbers in another way humans would perceive them: leading zeros can be ommitted for a human, but not for a computer. Let's say that you have a list of 12 files that you just named using numbers, e.g. like this:
  `1.jpg`, `2.jpg`, `3.jpg`, `4.jpg`, `5.jpg`, `6.jpg`, `7.jpg`, `8.jpg`, `9.jpg`, `10.jpg`, `11.jpg`, `12.jpg`
  A human would sort them like this:
  - 1.jpg
  - 2.jpg
  - 3.jpg
  - 4.jpg
  - 5.jpg
  - 6.jpg
  - 7.jpg
  - 8.jpg
  - 9.jpg
  - 10.jpg
  - 11.jpg
  - 12.jpg
  , but a computer won't: your webserver will sort them like this:
  - 1.jpg
  - 10.jpg
  - 11.jpg
  - 12.jpg
  - 2.jpg
  - 3.jpg
  - 4.jpg
  - 5.jpg
  - 6.jpg
  - 7.jpg
  - 8.jpg
  - 9.jpg
  That's why it's advisable to fill the names with leading zeroes in the first place. For that purpose, you need to estimate the maxmimum number of files that will reside in a particular folder. That maximum determines the number of digits that your file names will need: if the max. number of files will be 99 within a folder, you can use 01 to 99. If the maximum number of files will be 200, you will have to use three digits, so your first file needs to be named 001.jpg, the second one 002.jpg and so on. Of course your file names can be alpha-numeric, so you can come up with a combination of letters and numbers, e.g.
  - brussels001.jpg
  - brussels002.jpg
  - brussels003.jpg
  - brussels004.jpg
  - brussels005.jpg
  - brussels006.jpg
  - brussels007.jpg
  - brussels008.jpg
  - brussels009.jpg
  - brussels010.jpg
  - brussels011.jpg
  - brussels012.jpg