# HTML5 Image Uploader Readme #

The primary goal of this project is ImageUploader.js, a javascript module which can perform client-side resizing of images and uploads to a remote server using only HTML5 features (e.g. the Canvas and FileReader APIs).

For demonstration purposes this is packaged with a Java web application with a RESTful service to handle the uploaded images. This is an Apache Maven project, use "mvn clean install" to build the webapp and "mvn jetty:run" to run the app on localhost:8080

## Installation and Requirements ##
Include the ImageUploader.js file into your HTML page. Dependencies (include them first):

- **[Exif.js](https://github.com/exif-js/exif-js)**, a JavaScript library for reading EXIF image metadata 

## Usage ##

Create a new ImageUploader, passing in a javascript object hash of config, e.g.

```javascript
var uploader = new ImageUploader(config);
```

Where **config** contains the following properties:

### Obligatory properties ###

- **inputElement** - A file-type input element
- **uploadUrl** - The URL to POST uploaded images to

### Optional properties ###
#### Size restriction properties ####
These properties are used as conditions when the image should be scaled down proportionally before upload. If several properties are applied, then the image will be scaled down to the maximum available size that will fit all the conditions.

- **maxWidth** - An integer in pixels for the maximum width allowed for uploaded images, selected images with a greater width than this value will be scaled down before upload. Default value: 1024.
- **maxHeight** - An integer in pixels for the maximum height allowed for uploaded images, selected images with a greater height than this value will be scaled down before upload. Default value: 1024.
- **maxSize** - A float value in megapixels (MP) for the maximum overall size of the image allowed for uploaded images, selected images with a greater size than this value will be scaled down before upload. The size of the image is calculated by the formula `size = width * height / 1000`, where `width` and `height` are the dimensions of the image in pixels. If the value is null or is not specified, then maximum size restriction is not applied. Default value: null. For websites it's good to set this value around 1.7: for landscape images taken by standard photo cameras (Canon, Nikon, etc.), this value will lead to scaling down the original photo to size about 1600 x 1000 px, which is sufficient for displaying the scaled image on large screen monitors.  
- **scaleRatio** - Allows scaling down to a specified fraction of the original size. (Example: a value of 0.5 will reduce the size by half.) Accepts a decimal value between 0 and 1.

#### Other properties ####
- **quality** - A float between 0 and 1.00 for the image quality to use in the resulting image data, around 0.9 is recommended. Default value: 1.0.
- **autoRotate** - A boolean flag, if true then EXIF information from the image is parsed and the image is rotated correctly before upload. If false, then no processing is performed, and unwanted image flipping can happen. This flag is useful for JPEG images that were taken on a camera or mobile phone (like iPhone) that can save the image with arbitrary orientation and specifies the correct orientation in the EXIF tag. This tag should be parsed and related rotation should be applied for correct visualization of the image. Examples of such images you can find in the `images/exif` folder. Recommended and default value: true.
- **timeout** - A number in milliseconds specifying the maximum time to wait for file uploads to finish, after which they will be aborted.

#### Debug properties ####
- **debug** - A boolean flag to show the images in a `
` on the containing page before upload. Default value: false.
- **workspace** - An element within which images are appended before upload (when **debug** is set to true). If not specified, then a new `
` tag will be appended to the end of HTML body where the images will be rendered.

#### Callback properties ####
- **onScale** - A function which is invoked when final image is generated right before the upload starts. 1 argument passed: image data in data URL format. This callback function is useful for displaying a thumbnail (preview) of the selected image with correct orientation (the autoRotate option should be set to true).
- **onProgress** - A function which is invoked on upload progress, with a single argument of an object containing the following:

 - **total** - The total number of images selected for upload
 - **done** - The number of images uploaded so far
 - **currentItemTotal** - The number of bytes to be uploaded for the currently uploading image
 - **currentItemDone** - The total number of bytes to upload for the current image

- **onFileComplete** - A function invoked on completion of uploading each selected image which is passed two arguments, the first is the event object from the XmlHttpRequest, and the second if the corresponding File object from the input element
- **onComplete** - A function invoked on completion of all images being uploaded (passed no arguments)

## Example ##
Below is an example of using the ImageUploader.js for uploading images on HTML page and further processing of the images at the server.
  
### HTML ###
In our example we have a page with 3 input elements for selecting files that will be uploaded. When user selects a file, it will start to upload automatically. The user can select 1 file per input element.
 
We will use the following additional libraries (they are not required by the ImageUploader.js, but we will use them to make our example look pretty):

- [UIKit](https://getuikit.com/), it allows to apply some nice CSS styles (the name of the classes begin with `uk-` prefix). In our case we will use it to show:
	- button for selecting a file instead of standard rectangular input box.
	- show progress bar as indicator of uploading progress.
- [jQuery](https://jquery.com/), to write less JavaScript code. If you don't like jQuery, you can still use ImageUploader.js with pure "vanilla" JavaScript.

Screenshot of the resulting HTML page:

![Screenshot](https://github.com/rvalitov/HTML5-ImageUploader/raw/master/images/wiki/html-page.jpg)

The progress bar becomes visible when the user selects the image. It becomes hidden after the image upload completes.

The code of HTML page:

```HTML


	
	
	

	
	
	
	


	

		

			Select and upload image
			
			
			

				
Uploading, please wait...
				

					

				
			
		
	
	

		

			Select and upload image
			
			
			

				
Uploading, please wait...
				

					

				
			
		
	
	

		

			Select and upload image
			
			
			

				
Uploading, please wait...
				

					

				
			
		
	


```

Notes:

- In the code above we use `accept="image/jpeg,image/jpg"` to limit the file types that user can select. This approach works with all modern HTML5 browsers (desktop and mobile). But keep in mind, that the user can bypass this limitation and select arbitrary file. We will do some additional validation of file extension in the JavaScript code below.
- The input tag contains additional attributes such as `data-id` and `data-product`. We use them to show how you can add extra information to your input data and then pass it to the server. It can be useful when the HTML page is generated dynamically by the server (for example, using PHP, Perl or some other script).
- We add class `image-upload` to the input elements in order to mark out those, that should be processed with ImageUploader.js. Such approach allows to have different input elements in HTML page without conflicts.

### JavaScript ###
Below is the code of custom.js, which contains code for managing the HTML page (comments are in the code):

```javascript
jQuery(document).ready(function($){
	/* Initialization of input elements and ImageUploader.js */
	$("input.image-upload").each(function(index){
		var id=$(this).attr('data-id');
		var id_product = $(this).attr('data-product');
		var uploader = new ImageUploader({'inputElement': $(this).get(0), 
			'onProgress': function(info)
			{
				/* Updating the progress bar */
				if (info['currentItemTotal']<=0)
					return; 
				var progress=info['currentItemDone']*100.0/info['currentItemTotal'];
				$('#upload-progress-'+id+' div').css('width',progress+'%');
			}, 
			'onComplete': function()
			{
				/* Enable upload button */
				$('#upload-button-'+id).removeProp('disabled');
				/* Hide progress bar */
				$("#upload-container-"+id).addClass("uk-hidden");
			},
			/* Add rand parameter to prevent accidental caching of the image by the server */
			'uploadUrl': 'index.php?action=upload_image&id_image=' + id + '&id_product=' + id_product + '&rand=' + new Date().getTime(),
			'debug': true
			});
	});
	
	/* The function below is triggered every time the user selects a file */
	$("input.image-upload").change(function(index){
		/* We will check additionally the extension of the image if it's correct and we support it */
		var extension = $(this).val();
		if (extension.length>0){
			extension = extension.match(/[^.]+$/).pop().toLowerCase();
			extension = ~$.inArray(extension, ['jpg', 'jpeg']);
		}
		else{
			event.preventDefault();
			return;
		}
		
		if (!extension)
		{
			event.preventDefault();
			console.error('Unsupported image format');
			return;
		}
		var id=$(this).attr('data-id');
		/* Disable upload button until current upload completes */
		$('#upload-button-'+id).prop('disabled',true);
		/* Show progress bar */
		$("#upload-container-"+id).removeClass("uk-hidden");
		/* If you want, you can show a preview of the selected image to the user, but to keep the code simple, we will skip this step */
	});
});
```

### PHP ###
This part of the example covers the issue of processing the files on the server. In our example we use `index.php` as a file that is used to recieve and save the images from ImageUploader.js. The code below is written in PHP, but you can use it with any other language that you are familiar with.

```php

```