

Author: etienne_sf
Accound etienne_sf (on sourceforge and coppermine forums)
Mail: etienne_sf@sourceforge.net (please avoid sending mails on this address, see below for support).



1) SUMMARY
2) USER GUIDE
3) TECHNICAL DESCRIPTION
4) INSTALLATION
5) CONFIGURATION
6) HOW TO SOLVE PROBLEM ?
7) SUPPORT


1) SUMMARY

  This pack is an add-on (plugin) for the coppermine gallery, that allow you to batch upload pictures from an applet. This applet allows the user to preview and rotate pictures before upload.
  The picture are resized to the gallery maximum size before upload: this make quicker upload, and allow easy upload of pictures from modern camera, even on ISP that has a too low maximum upload size.
  After upload, the user can modify the picture properties (title, description, key words) on one unique page.

  
  A sample coppermine gallery is available, if you want to take a look to it :
http://etiennegauthier.free.fr/coppermine/jupload.php

login/pass: 
    copermine / jupload   (oups!, I forgot one 'p' into my first message)
    or
    coppermine / jupload  (so there is now two available login to test the jupload plugin)



2) USER GUIDE

By using this applet, the main user improvements are:
- Uploading several pictures (no limit) in only _two_ web pages:
   - Page1 (click on the JUpload menu item or open jupoad.php page): select album (or create/update album), 
   select picture files, preview and/or rotate them, upload,
   - Enter picture comments in the album properties page (for all pictures at once).
- Upload is quicker, as pictures are resized by the applet before upload,
- The user can enter comments for all uploaded pictures in one web page (instead of one by picture),
- The jupload.php script allows the user to both: manager albums (owned by the user) and upload pictures,
- Upload pictures without having to manually resize them before upload (my Canon EOS20D pictures are bigger than 
the upload limit of my free ISP hosting).
- When you're browsing to a category or an album, click on the JUpload link: the upload page will open, with this 
category or album selected.
  
  
The applet allows the user, before upload, to:
- Select multiple files on his hard drive, and either :
  - **Drag'n drop** files from your favorite picture editing tool,
  - Copy / Paste them onto the applet
- Preview pictures,
- Display a full screen picture (by clicking on the previewed picture),
- Rotate the picture right or left,
- Download pictures and select the upload album on the same web page (with the jupload.php script),
- Upload all pictures/files in one click,
- Not wait for each picture upload : if the session times out after upload, all pictures are correctly stored in the selected album,
- Edit all picture properties in one page (the album properties page is automatically opened after a successfull upload). Only the pictures uploaded by the current user can be updated by this page. Thus, it is impossible to use this page to update other's pictures.





3) TECHNICAL DESCRIPTION


Within php, I added:
- The /jupload.php. It is largement inspired by the xp_publish script. I removed everything I didn't want, and add 
albums handling. From this unique page, the user can: create, rename, and change desription of its albums. Each time 
he selects an album, the applet is updated to target this album.
- french.php and english.php. I added necessary text within it. In your release notes for patches, you talked abut plugin. I didn't take a look on how to handle jupload as a plugin.
- [Now useless] Create a particular theme, to add JUpload in the navigation menu.
- No special coppermine configuration.


I updated the 'Java Multiple File Upload Applet (JUpload)' sourceforge project (http://jupload.sourceforge.net) : this is an applet, that allow multiple files uploads. 
  This applet is now able to manage picture (see below, for the functionalities I added). I added a 'configuration' to use this applet with coppermine.
  


Technically, this applet:
- Is open source, and available here: http://jupload.sourceforge.net
- Is a stable version. It has been tested by a lot of other people, now.
- Is signed, to allow access to the user's hard drive (a user confirmation is asked by the JVM). You can sign it with your own certificate. See http://jupload.sourceforge.net for all details.
- Is displayed in the current language. Currently available (2.0.0): english, french, dutch, german, esperanto, spanish.
- Retrieves the session from the navigator, to upload files within the same session (it get cookies from the navigtor, and the current server protocol back from the server, in an applet parameter: not nice, but I didn't find any other way),
- Resizes picture to the maximum coppermine size _before_ upload : the network traffic is smaller/quicker, and the load on the server is smaller. The resized pictures are now of good quality (since 2.0.0). This resizing functionnality is especially useful for pictures made by modern camera: their pictures are often too big for the maximum upload size allowed on servers.


4) INSTALLATION / UPDATE

 
To use this pack, you just have to unzip it in your coppermine root directory.

To get access to it, you can
1) [Manual] Call the URL http://your.web.site/your_coppermine_folder/jupload.php by manually type this URL in your navigator. This allows you to test this plugin, without giving it 'open' access, until you are satisfied with it.
2) [Use the plugin manager] This is the best solution... since 2.1.0. Just use the upload button on the plugin 
management page, to upload it, then click on the 'i' to install it or update it. Doing will keep your JUpload configuration, is you saved one.

Note: it also works with the standard hardwire theme, despite its special button management!

Until 2.0.0, you have to do this (after unzipping the jupload package in the coppermine root directory):
	a) Connect as an admin, 
	b) Click on the 'configuration' button, 
	c) Select the 'general setting' area, 
	d) Check the 'yes' is selected for the 'activate plugin' choice (if 'no', select 'yes', and don't forget to click on 'Save configuration', on the bottom of the page),
	e) Click on the 'admin the plugins' link.
	f) Find the jupload plugin in the list. If it is not installed, click on the beautifull little 'i', in the right column to activate it. The JUpload link should now be displayed on the left of the login/logout menu entry, whatever theme is selected.
3) [Use a specific theme] (Useless, since version 2.0.0 : you should use the standard plugin manager, see above) Change the gallery theme to 'jupload_rainy_day'. I just added a link to Jupload in the top menu.
4) Add the jupload link to your current theme. To do this, :
  a) Create a new theme (just copy all theme files to a new subdirectory of theme). This will prevent that you loose your modification when upgrading coppermine.
  b) Edit the jupload_rainy_day/theme.php, and search for jupload
  c) Copy the found line to your theme.php. The link for this new menu entry should be YourCoppermineRootInstallation/jupload.php



5) CONFIGURATION

This plugin has configuration parameters. Before 2.6.0, these parameters are stored in the 
plugins/jupload/user/config.inc.php file. This file is not packaged in JUpload releases. So __ugrading JUpload plugin
won't erase your current configuration__.
Since 2.6.0, the JUpload configuration is saved in the Coppermine config table.

You can update the JUpload configuration this way:
1) Connect as an admin
2) Go to the Coppermine ''Configuration'' page
3) Click on 'General parameters'
4) Click on 'Plugin management'
5) If the Jupload plugin is not installed, install it
6) Click on ''JUpload configuration''.

You'll find below the list of available paramaters. All details about the JUpload configuration, and each parameter 
are given in the config file and on the config page:
* Parameter that has no link with upload:
  - albumShowEditFields: allows to hide the album name and description on the upload page. Useful if standard users 
  may only upload to existing albums (not create or update albums).
  - alwaysVisible: 1 if the JUpload link is always visible. If 0, the JUpload link is only visible to users that
  may upload pictures. If the link is visible, a user who may not upload pictures (or is not logged in) will be 
  redirected to a connection page. [Since 3.0.0] This parameter also allows you to restrict access to the plugin 
  to both administrators and a given user group.
  - appletHeight and appletWidth (since 2.6.0): allows control on the size of the applet on the upload page.
  - basicHttpAuthentication (since 2.5.3): allows upload to an URL protected by a basic authentication.
  - fileChooserIconFromFileContent (since 2.6.0): if set to true, the icon of the files in the file chooser are 
  calculated from the image content. Otherwise: system default.
  - fileChooserIconSize (since 2.6.0): Size of the icon described here above.
  - generateDefaultPictureTitle: Controls whether the plugin will define a default picture title for the uploaded
  file. This default title will be based on the filename.  
  - highQualityPreview: Indicate whether the pictures displayed on the applet are high or low (less CPU) quality. Of
  course, all uploaded pictures are treated in high quality.
  - jarPath: allows the applet to be integrated in Coppermine, even when Coppermine is itself a plugin of another
  tool. It controls the path where the jupload.jar file is.
  - linkComment (since 2.5.5): Allows the admin to change the explanation that is displayed, when the user put his
  mouse over the JUpload link.
  - linkKeepStandardUpload (since 2.5.6): Allows the admin to change the explanation that is displayed, when the user 
  put his mouse over the JUpload link.
  - linkTitle (since 2.5.5): allows the admin to change the text of the JUpload link.
  - sessionManagement (since 3.0.0): allows to use internal JUpload session management. Make the plugin work with 
  some specific bridge configuration, where standard session management leads to a 'no permission' error.
  

* Parameters to control the upload itself:
  - maxChunkSize: Define the maximum number of bytes that may be uploaded at once. A file bigger will bu splitted in 
  chunks. The whole file will be re-created on the serve, once all chunks have been sent.
  - maxFileSize. Maximum file size for an uploaded file. It can be bigger than the maxChunkSize. This parameter
  overrides your Coppermine configuration for JUpload.
  - maxNonTransformedPictureSize. This parameter is important to control who of the applet or the server
  resizes pictures bigger than the maximum picture size (in pixels) you've defined in your Coppermine configuration.
  - pictureCompressionQuality: controls the jpeg compression. Default is 0.8. It creates pictures of the same weight
  as the native Coppermine.



5) HOW TO SOLVE PROBLEMS ?

Before asking for support, you should :
a) Check that standard upload works with the same login.
b) Put the debug on. To do this, you can set the applet debugLevel parameter to 100, in the plugins/jupload/upload_page.php script, or, while using the applet, do a CTRL + right-click on the status area of the applet, and select the 'debug on' entry in the popup menu that should appear.

A little FAQ

  * You're using Firefox on mac
    * Seems like the bridge between Firefox and Java doesn't exit on mac! This bridge is mandatory for the applet.
    * This tool should allow you to use the applet (please confirm it to me): 
      * http://javaplugin.sourceforge.net
  * You're using IE7 on Vista
    *  Crash was reported. To be confirmed.
  * You get a PHP error
    * Check your PHP version. The plugin can't work for PHP earlier than 4.3.0.
  * You don't see the whole applet.
    * Take a look to the configuration parmeters appletWidth and appletHeight.
  * Your Coppermine installation is a plugin (bridge ?) in another tool, and the applet i not displayed
    * Take a look to the jarPath plugin.
  * When uploading through the applet, ou get a 'no permission error', or any other message indicating that you're
  not connected.  Seems to occur sometimes, when your Coppermine installation is a plugin (bridge mode).
    * Take a look at the sessionManagement configuration parameter, since 3.0.0.
  * You want to restrict access to the plugin.
    * Take a look at the alwaysVisible configuration parameter, especially since 3.0.0.
  * Picture is transformed (picture file is smaller, for instance), but I don't want it !
    * Take a look at the explanation going with the pictureTransmitMetadata configuration parameter.
  * What else ?
    * Get the debug output (see below)

How to get the debug output ?

Usually, problems occur during upload, so check the debug output, to see what the server answered. To do this:
- Debug must be on (put it on by CTRL+RIGHT CLICK on the file list)
- Select all in the status area (click into it, then CTRL-A to select the whole text)
- Copy it into a text editor, and try to read it.
- The server response is written between the lines containing '-------- Server Output Start --------' and '--------- Server Output End ---------'.

What you should see:
- First line MUST contain '200 OK' (e.g. full line should look like 'HTTP/1.1 200 OK'). If you get any other number, you have a problem that is local to your installation. Check this page to know what means this return code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
- If you get 200 OK, that means that you get a 'normal' response from the server, that is from coppermine. But this response can be a message explaining an error to you. So, check the first empty line. The real response from coppermine comes after. 
- This response should be a simple line containing 'SUCCESS'. If so, upload was Ok. Any problem you have is after. 
- If not, the result can be a simple error message or a full HTML page.
  - If it is a simple error message, see if you can correct it.
  - If it is a full HTML page, you can copy the full server response (between the empty line and the line containing '--------- Server Output End ---------'), save it into a file named 'err.html', and open it with your navigator. You'll be able to see the coppermine response. You can then understand, and try to correct the problem.



7) SUPPORT

a) To get support about the coppermine plugin: the best way is to post a message into the coppermine plugins forum, for this applet. I'll receive a notice in my personal mailbox.
http://coppermine-gallery.net/forum/index.php?topic=43432

b) To get support about the applet itself, the best way is to post a message into the sourceforge forums. Here again, I'll receive a notice in my personnal mailbox.



Regards
Etienne
Sourceforge coppermine and account: etienne_sf


