File Picker

Were possible we follow W3C specs as close as possible, but there's no spec for file picker element, so we came up with our own. Our file picker is not simply a part of upload procedure. It is more or less standalone and can also be used in conjunction with FileReader component for example, in order to get hold of raw file data.

Table of Contents

• Example
• Options
  • browse_button
  • container
  • accept
  • runtime_order
• Events
  • ready
  • mouseenter, mouseleave, mousedown and mouseup

Example

	<div id="container">
		<a id="file-picker" href="javascript:;">Browse...</a>
	</div>

	<script>
		var fileInput = new mOxie.FileInput({
			browse_button: 'file-picker', // or document.getElementById('file-picker')
			accept: [
				{title: "Images", extensions: "jpg,gif,png"} // accept only images
			]
		});

		fileInput.onchange = function(e) {
			// do something to files array
			console.info(e.target.files); // or this.files or fileInput.files
		};

		fileInput.init(); // initialize
	</script>

## Options ### browse_button

Single required option for the FileInput to be created properly (all other options are optional). Specifies the element on the page that should become a file picker. Component can even be instantiated like this:

var fileInput = new mOxie.FileInput('file-picker');

### container

By default FileInput will append it's own HTML structures to the immediate parent of the browse_button element. In case you'd like some other element to keep the structure, you can it as a value for container option. Component accepts both: ids or DOM elements.

### accept

File picker can be configured to accept only files of specific format - only images, or only archive files. However there is a slight stumble point - different runtimes denote file formats differently. HTML5/HTML4 use MIME types, while Flash/Silverlight rely on extensions. accept option can take in both, and convert them into each other internally.

It can be array of key-value pairs:

	...
	accept: [
		{ title: "Images", extensions: "jpg,gif,png" },
		{ title: "Archives", extensions: "zip" }
	]
	...

Or a comma-delimited string of MIME types:

	...
	accept: "image/*,application/zip"
	...

Check this entry from Plupload FAQ as well.

### runtime_order

This setting is optional. If not specified FileInput (just as any other moxie component) will use default order: html5,flash,silverlight,html4 - html5 will be tried first and then - flash, etc, until functional runtime is found. Setting is useful if you want to alter the order or omit some runtimes completely.

## Events ### ready

Initialization of the file picker might take some time, especially for non native runtimes (like Flash and Silverlight). It is asynchronous operation. Obviously it might be undesirable to have a picker element that looks like functional one, before it truly is. You can use event ready to catch the moment when picker becomes truly available and style your picker element accordingly.

<div id="container">
	<a id="file-picker" class="disabled" href="javascript:;">Browse...</a>
</div>

<script>
	...
	fileInput.onready = function() {
	    mOxie.removeClass(document.getElementById('file-picker'), 'disabled');
	};
	...
</script>

### mouseenter, mouseleave, mousedown and mouseup

Any DOM element can be turned into file picker. We do not automatically style file picker element in any way. You are free to provide your own stylings for the picker element and we will attach file dialog to it. After initialization your original picker element might stay or not stay accessible, depending on the runtime. This might successfully block any :hover or :active interactivity on top of it. This is why we provide mouseenter, mouseleave, mousedown and mouseup events on FileInput component.

...
fileInput.onmouseenter = function() {
    mOxie.addClass(document.getElementById('file-picker'), 'hover');
};

fileInput.onmouseleave = function() {
    mOxie.removeClass(document.getElementById('file-picker'), 'hover');
};

fileInput.onmousedown = function() {
    mOxie.addClass(document.getElementById('file-picker'), 'active');
};

fileInput.onmouseup = function() {
    mOxie.removeClass(document.getElementById('file-picker'), 'active');
};
...