Skuteczny upload plików z Plupload oraz jQuery

Twórcy znanego edytora WYSIWYG dedykowanego dla JavaScriptu tym razem zaprezentowali komponent do uploadu plików na serwer - Plupload. Oprócz opracowanych już przez innych metod wrzucania plików przy wykorzystaniu iframe'mów czy wykorzystaniu elementów Flash skupia w sobie 6 różnych metod - jedna z nich jest wybierana, w zależności od dostępności.

Technologie i funkcjonalności

Zastosowane metody uploadu stosują następujące technologie:

• HTML5
• Gears
• Flash
• Silverlight
• BrowserPlus (rozszerzenie do przeglądarek Internet Explorer, Firefox, Chrome, Safari)
• HTML4 (iframe)

Oprócz standardowej obsługi wysyłania plików istnieją także dodatkowe funkcjonalności - jak np. zmniejszanie obrazków po stronie klienta oraz obsługa postępu wysyłania. Poniżej tabelka z możliwościami dostępnymi dla poszczególnych technologii (pobrane ze strony producenta).

Funkcjonalność	Flash	Gears	HTML 5	Silverlight	BrowserPlus	HTML 4
Obsługa HTTP Chunked Transfer Encoding
Drag/Drop			1
Zmiana rozmiarów plików PNG			2
Zmiana rozmiarów plików JPEG			2
Filtrowanie typów			3
Wrzucanie strumieniowe
Obsługa multipart/form-data			4
Ograniczenia wielkości pliku
Obsługa postępu

¹ Drag/Drop tylko dla Mozilla Firefox 3.5+ - Chrome oraz Opera nie wspierają póki co tej funkcjonalności
² Obsługa zmiany rozmiarów tylko dla Mozilla Firefox 3.5+ dla ustalonej jakości
³ Póki co nie wspierane przez żadną z przeglądarek
⁴ Multipart póki co obsługiwany tylko przez Firefox (silnik Gecko)

Mnogość różnych dostępnych typów upload'u pozwala na stosowanie tego plugin'u praktycznie w każdej współczesnej przeglądarce internetowej (ale także w IE6).

Wdrożenie

Po ściągnięciu paczki z serwerów Plupload - znajdziemy w niej szereg plików źródłowych. Jeżeli nie zamierzamy zmieniać kodu źródłowego, a jednocześnie móc korzystać ze wszystkich dostępnych do naszego dokumentu dołączamy plik plupload.full.min.js. Należy pamiętać, że jest to plugin do jQuery, więc wcześniej musimy dołączyć także sam framework jQuery.

<script src="/js/jquery.js" type="text/javascript"></script>
<script src="/js/plupload.full.min.js" type="text/javascript"></script>

Oprócz tego w celu ew. uruchomienia Gears'ów oraz BrowserPlus konieczne jest dodanie dwóch dodatkowych plików (gears_init.js jest także dołączony do pobranego zipa).

<script type="text/javascript" src="/js/gears_init.js"></script>
<script type="text/javascript" src="http://bp.yahooapis.com/2.4.21/browserplus-min.js"></script>

Ostatnimi potrzebnymi plikami są binarki dla Flasha oraz Silverlight'a (plupload.flash.swf oraz plupload.silverlight.xap) - najlepiej je umieścić w katalogu razem z js'ami.

Istnieją dwie metody uruchomienia pluginu - jako Widget (z predefiniowanym UI) oraz jako tylko jako dostęp do API (wówczas sami podajemy, w którym pojemniku znajduje się lista plików, co służy za przycisk do przeglądania oraz przycisk do wysyłania plików).
W pierwszym przypadku wykonujemy polecenia

$("#uploader").pluploadQueue({
   runtimes : 'gears,flash,silverlight,browserplus,html5',
   url : 'upload.php'
   flash_swf_url : '/js/plupload.flash.swf',
   silverlight_xap_url : '/js/plupload.silverlight.xap'
});

Aby samemu uzyskać dostęp do API tworzymy obiekt plupload.Uploader

var uploader = new plupload.Uploader({
   runtimes : 'gears,html5,flash,browserplus,html4',
   browse_button : 'pickfiles_{$id}',
   ...
});
uploader.init();

Dostępne parametry

• runtimes - podaje kolejność wykrywania poszczególnych metod upload'u - dostępne wartości to gears, flash, silverlight, browserplus, html5, html4 - kolejne wartości rozdzielane przecinkami
• url - adres URL, pod którym znajduje się skrypt obsługujący upload pliku
• max_file_size - maksymalna wielkość pliku - podawane jako ciąg znaków np. 10b, 10kb, 10mb
• chunk_size - podział pliku na mniejsze części (przydatne jeśli jest duży plik, a serwer ma ograniczenia wielkości żądania) - w celu wyłączania tej funkcjonalności, wystarczy nie podawać tego parametru
• unique_name - jeżeli jest wartość true, wówczas jest generowana unikalna nazwa pliku
• resize - struktura dotycząca zmiany wielkości obrazka (w przypadku upload'u obrazka):
  
  • width - maksymalna wysokość
  • height - maksymalna szerokość
  • quality - jakość (od 0 do 100)
• filters - struktura dotycząca filtru na typach plików w wyskakującym okienku wyboru plików:
  
  • title - tytuł wyświetlany na liście rozwijanej
  • extensions - lista rozszerzeń (rozdzielone przecinkami)
• flash_swf_url - ścieżka do binarki Flash'a
• silverlight_xap_url - ścieżka do binarki Silverlight'a
• browse_button - przycisk obsługujący zdarzenie 'Przeglądaj' - ciąg znaków z id (niewymagane dla opcji widget)
• drop_element - element, na który można przeciągać pliki (do zdarzenia drag/drop)
• container - element, który zawiera elementy potrzebne do działania pluginu
• multipart - flaga ustawiająca obsługę multipart
• multipart_params - parametry, które mają być przesłane razem z plikiem

Linki

Strona domowa projektu Plupload
Dokumentacja
Przykłady użycia

Życzę miłej zabawy :)