blondak/MultipleFileUpload
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Repository files navigation
Tato dokumentace je napsána v Texy. Správně naformátovanou byste ji měli najít zde: http://addons.nette.org/cs/multiplefileupload?rev=50 MultipleFileUpload ################## .[perex] MultipleFileUpload (zkráceně MFU) je doplněk pro Nette Framework, který vašim uživatelům umožní pohodlně, jednoduše a interaktivně odesílat hromady souborů. Komfort nabízí nejen uživateli, ale i programátorovi. Uživatel může na pár kliknutí odeslat celé fotoalbum a programátorovi stačí na implementaci tohoto doplňku pouhé 2 řádky kódu. Navíc tento doplněk podporuje AJAX pro maximální rychlost a uživatelské pohodlí! I na uživatele se staršími prohlížeči se myslelo. Pokud prohlížeč nesplňuje minimální požadavky, uživatel může odeslat soubory standardním způsobem. |*Autor doplňku | "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 |*Autor driver(ů) | "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 (sqlite a log driver), "Martin Sadový":http://forum.nette.org/cs/profile.php?id=1876 (dibi driver) |*Autor interface(ů)| "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 (HTML4SingleUpload, Plupload, Uploadify), "Roman Vykuka":http://forum.nette.org/cs/profile.php?id=2221 (SWFUpload) |*Inspirováno | http://forum.nette.org/cs/viewtopic.php?pid=15098#p15098 |*Licence | New BSD License |*Diskuse | http://forum.nette.org/cs/2386-addon-multiplefileupload-multiplefileupload-form-control |*Demo | http://multiplefileupload.projekty.mujserver.net/ |*Stav | Stabilní. Nicméně pár problémů k vyřešení to ještě je - viz kapitola "Známé problémy":[#toc-zname-problemy] |*Nette | viz "závislosti":[#toc-zavislosti] Instalace ********* 1. Zkopírujte následující soubory: - app/controls/MultipleFileUpload/* - document_root/css/MultipleFileUpload/* - document_root/images/MultipleFileUpload/* - document_root/js/MultipleFileUpload/* - document_root/swf/MultipleFileUpload/* - document_root/xap/MultipleFileUpload/* 2. Do bootstrapu za registraci "RobotLoaderu":http://doc.nette.org/cs/nette-loaders#toc-nette-loaders-robotloader a před `$application->run();` přidejte následující řádku. /---code php MultipleFileUpload::register(); \--- 3. Do vašeho layoutu případně do stránek, kde chcete používat MFU, přidejte následující řádek před tag `</head>` JavaScriptové knihovny, které jsou společné (pravděpodobně je budete používat ve své aplikaci) - viz `@layout.phml` v GITu. /---code html {!=MultipleFileUpload::getHead()} \--- Tímto krokem načtete a zaregistrujete *Multiple File Upload*. .[note] Pokud používáte Nette 0.9.2 nebo nižší, čtěte zde: http://forum.nette.org/cs/2566-httpuploadedfile-bug-pri-safe-mode-nema-opravneni-pri-presunu-souboru . V Nette 0.9.3-RC je už tato "chyba" opravena. http://github.com/dg/nette/commit/f36e5f07e0df3580ebae8a3b26562f8ae53e84a1 .[note] Pokud na vašem serveru běží PHP pod (Fast)CGI, je doporučená verze Nette 0.9.4. V této verzi je už opravené získávání hlaviček. Viz http://github.com/nette/nette/commit/d6b7f0c31ae3e3fcedf0e0a914bae84a260119db. .[note] **Nette 2.0** zatím není oficiálně podporováno, nicméně díky skvělé, aktivní komunitě můžete již dnes využívat originální "MultipleFileUpload na Nette 2.0 a PHP 5.3":http://projekty.mujserver.net/nette/MultipleFileUpload_pro_PHP5.3/. A potom už můžete začít **Multiple File Uploader používat**. Použití ******* /---code php $f = new AppForm($this,$name); $f->addMultipleFileUpload("pokus1","Testík",20) ->addRule("MultipleFileUpload::validateFilled","Musíte odeslat alespoň jeden soubor!") ->addRule("MultipleFileUpload::validateFileSize","Soubory jsou dohromady moc veliké!",1024); // 1 KB \--- .[note] Do formuláře je potřeba opravdu zadávat přímo callback, protože ZATÍM není podporována validace na straně klienta! Jako hodnotu MFU ve formuláři dostanu pole ve kterém je každý soubor validní (prošel HttpUploadedFile::isOK()) a je instancí HttpUploadedFile. Všechny soubory co zůstanou v tempech po odeslání formuláře budou smazány. Takto vypadá pole co dostanete ke zpracování (`$hodnoty = $form->getValues();`): /---code php array(1) { 0 => object(HttpUploadedFile) (5) { "name" private => string(15) "application.ini" "type" private => string(24) "application/octet-stream" "size" private => int(164) "tmpName" private => string(107) "xxx" "error" private => int(0) } } \--- Vzhled prvk A044 u můžete upravovat v šablonách `MultipleFileUpload-withJS.phtml` a `MultipleFileUpload-withoutJS.phtml`. Popřípadě zde můžete i měnit nastavení uploadify. Závislosti ********** - Nette - minimální verze Nette 0.9.1, 0.9.2 (nutnost přepsat "HttpUploadedFile::move()":http://forum.nette.org/cs/2566-httpuploadedfile-bug-pri-safe-mode-nema-opravneni-pri-presunu-souboru) - **doporučená verze Nette 0.9.3** (nebo vyšší) - Nette 1.0-dev - http://forum.nette.org/cs/profile.php?id=2529. - Nette 2.0 zatím není oficiálně podporováno, **nicméně díky skvělé, aktivní komunitě můžete již dnes "využívat originální MultipleFileUpload":http://projekty.mujserver.net/nette/MultipleFileUpload_pro_PHP5.3/ na Nette 2.0 a PHP 5.3**. (hlavní díky v současné chvíli patří Matúši Matulovi, který se stará o verzi pro Nette 2.0) - nyní jsou zdrojáky na GIThubu, doufám, že se brzy objeví fork pro Nette 2.0 - JavaScript: Závisí na použitém interface - Například interface Uploadify: - [jQuery | http://jquery.com/], [Uploadify | http://www.uploadify.com/], [swfobject.js | http://code.google.com/p/swfobject/], [livequery | http://plugins.jquery.com/project/livequery/], [upravený ajax-form driver | https://github.com/jkuchar/MultipleFileUpload/blob/master/document_root/js/nette-ajax-form.js] - originální `jquery.uploadify.js` nefunguje s Internet Explorerem, protože má v id objektu pomlčku. IE to interpretuje jako mínus. Proto jsem vydal upravenou verzi, kterou najdete na GITu https://github.com/jkuchar/MultipleFileUpload/tree/master/document_root/js. - originální `swfobject.js` nefunguje v Internet Exploreru, protože Internet Explorer má bug s flashem ve formuláři. Upravenou verzi tohoto souboru najdete na GITu https://github.com/jkuchar/MultipleFileUpload/tree/master/document_root/js. Známé problémy ************** Uploadify ========= - pokud není k dispozici Flash Player, nenastane automatický fallback a ani není k dispozici ruční fallback na klasické nahrávání souborů HTML4SingleUpload ================= - nabídne se i pokud formulář funguje ajaxově (soubory se samozřejmě neodešlou). Nějaké nápady jak toto vyřešit? Drivery ******* Driver má za úkol skladovat informace o přenesených souborech a samotné soubory. V distribuci Multiple File Uploadu se driverů nachází hned několik. |----------------------------------------------------------------- | Driver | Autor | Licence | Umístění | Thread-safe | Popis | Instalace | Stav |----------------------------------------------------------------- | **SQLite v. 2** | "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 | New BSD | distribuce | ano | Ukládá informace o přenesených souborech do databáze SQLite. (využívá php_sqlite; nevyžaduje dibi) | Stačí povolit zápis (chmod(0777)) ve složce app/controls/drivers/Sqlite/database.sdb. | **Doporučený, Stabilní** | **Dibi** | "Martin Sadový":http://forum.nette.org/cs/profile.php?id=1876 (prvotní implementace) + "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 (učesáno; přidán workaround pro http://forum.dibiphp.com/cs/1003-pgsql-a-znak-x00-oriznuti-zbytku-vstupu?pid=3840#p3840) | New BSD | distribuce | ano | Ukládá informace o přenesených souborech do jakékoli databáze, kterou podporuje Dibi. (vyžaduje Dibi; tabulku musíte v databázi ručně vytvořit; v distribuci přiloženy dumpy databází mysql (Martin) a postgres (Honza)) | Zprovozníte dibi, vytvoříte tabulku files v databázi. (viz dumpy databází) | **Experimentální** (nejspíš si ho budete muset poupravit právě pro vaši databázi, ale bez úprav by to mělo fungovat pod MySQL a PgSQL) | **Log** | "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 | New BSD | distribuce | ano | Nikam nic neukládá. Slouží pro vývojáře k zjištění pořadí volaných metod v driveru. Pro běžného uživatele nemá žádný význam. | Nakonfigurovat "Logger":http://addons.nette.org/cs/logger. | **Stabilní** A jak to v praxi zaregistrovat? Je to jednoduché. Podívejte se do souboru bootstrap.php v distribuci. Najdete tam zhruba toto: /---code php // Optional step: register driver // // As default driver is used Sqlite driver // @see http://addons.nettephp.com/cs/multiplefileupload#toc-drivery // // When you want to use other driver use something like this: Dibi::connect(array( "driver" => "postgre", "host" => "127.0.0.1", "dbname" => "MFU", "schema" => "public", "user" => "postgres", "pass" => "toor", "charset" => "UTF-8" )); //MultipleFileUpload::$queuesModel = new MFUQueuesDibi(); // do revize 69 MultipleFileUpload::setQueuesModel(new MFUQueuesDibi()); // od revize 69 (včetně) \---code Interfaces ********** Začal bych tím co to vlastně je. Je to jakýsi balíček s uživatelským rozhraním a jeho pozadím na straně serveru, které čeká na data od klientského rozhraní. Část na straně serveru má za úkol předat přijatá data ve specifikované formě modelu. Nejlépe pochopíte, pokud si zobrazíte již funkční interfacy v distribuci. V současné chvíli máme v distribuci tyto interfacy: |----------------------------------------------------------------- | Interface | Autor | Licence | Vyžadován JavaScript? | Popis |----------------------------------------------------------------- | **HTML4SingleUpload** | "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 | NewBSD | **Ne** | Implementuje standardní HTML4 odesílací políčka | **Plupload** | "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 | NewBSD | Ano | Implementuje "plupload":http://www.plupload.com/ | **SWFUpload** | "Roman Vykuka":http://forum.nette.org/cs/profile.php?id=2221 | NewBSD | Ano | Implementuje "SwfUpload":http://swfupload.org/; více informací o tomto interface na "fóru":http://forum.nette.org/cs/2386-addon-multiplefileupload-multiplefileupload-form-control?p=4#p37697. | **Uploadify** | "Honza Kuchař":http://forum.nette.org/cs/profile.php?id=1018 | NewBSD | Ano | Implementuje "Uploadify":http://www.uploadify.com/ Teď tedy čistě praktická a logická otázka, jak ten interface zaregistrovat a používat? Registrace v do MFU se dělá pomocí předání názvu třídy interface. V MFU jsou třídy interfaců pojmenování jako MFUUI a následuje název interface. Tedy například `MFUUIUploadify`. Poté už nám zbývá jen interface zaregistrovat. Jak na to nám ukáže příklad z bootstrapu. /---code php MultipleFileUpload::getUIRegistrator() ->clear() ->register("MFUUIHTML4SingleUpload") ->register("MFUUIUploadify"); \--- Jak vidíte nejdříve jsme získali od objektu MFU UIRegistrator. To je třída, která v sobě uchovává informace o zaregistrovaných interfacech. Tedy nejdříve jsme vymazali již zaregistrované výchozí hodnoty (HTML4SingleUpload, Uploadify). A nyní zaregistrujeme nějaký svůj interface. Pořadí můžeme libovolně měnit, jediné co musíme dodržet je, aby první registrovaný interface nevyžadoval JavaScript, protože ten jako jediný se vygeneruje do stránky, pokud ho prohlížeč nepodporuje. Pokud máte svoje klientské řešení a chcete ho používat s MFU, čtěte článek "Jak na vlastní interface?":[multiplefileupload/jak-na-vlastni-interface]. Podpora v prohlížečích ********************** Liší se interface od interface. Tedy postupně. HTML4SingleUpload ================= Nevím jak textové prohlížeče, ale jinak by měl být podporován všude. Plupload ======== - Všude, kde funguje Javascript. - Co jsem zkoušel, jdou odesílat opravdu gigantické soubory, nejvíce jsem zkoušel 6GB. Ale pozor, potom použije "knihovnu na zjišťování velikostí souborů":[bigfiletools], pokud ji potřebujete vědět. `HttpUploadeFile` vám bude vracet nesmysly, u takto velikých souborů. SWFUpload ========= *(Honza: Prosím autora o doplnění. Já jsem kompatibilitu netestoval. Nicméně bude to dost podobné jako uploadify)* Uploadify ========= |----------------------------------------------------------------- | OS | Prohlížeč | Verze | Kvalita podpory | Komentář |----------------------------------------------------------------- | Win7 | Google Chrome | 2 | <b> ***** </b> .<> | Bez výhrad | ^| ^| 4.1.249.1025 beta | <b> ***** </b> .<> | Bez výhrad | ^| Opera | 10.0 | <b> ***** </b> .<> | Bez výhrad | ^| ^| 9.65 | <b> ***** </b> .<> | Bez výhrad | ^| Firefox | 3.5 | <b> **** </b> .<> | O něco pomalejší než Google Chrome a Opera. Možná je to ale způsobeno nějakým nainstalovaným doplňkem. | ^| ^| 3.6 | <b> **** </b> .<> | O něco pomalejší než Google Chrome a Opera. Možná je to ale způsobeno nějakým nainstalovaným doplňkem. | ^| Internet Explorer | všechny | - .<> | Mezi soubory z nějakých důvodů chvíli čeká. Potřeba ošetřit několik chyb v IE/Flash, aby MFU vůbec fungovalo. (viz "Závislosti":[#toc-zavislosti]) | ^| ^| 8 | <b> *** </b> .<> | Soubory odesílá klidně v deseti vláknech. (ale každé vlákno vždy chvíli čeká) Tzn. funguje to v celku správně. | WinXP | ^| 6 | <b> * </b> .<> | Soubory odesílá pouze v jednom vlákně. Tzn. taky to nějak funguje. Pokud není váš prohlížeč v předcházející tabulce, tak prosím napište na fórum, zada ve vašem prohlížeči MFU funguje, či nikoli. A pokud ano, tak jak. Demo **** http://multiplefileupload.projekty.mujserver.net/ <iframe width="700" height="1000" frameborder="3" src="http://multiplefileupload.projekty.mujserver.net/"></iframe> GIT *** https://github.com/jkuchar/MultipleFileUpload/ .[note] Na GITu, tedy na oficiální větvi, je k dispozici pouze verze pro Nette 0.9. Pro verzi pro Nette 2.0 pokračujte do sekce "Závislosti":[#toc-zavislosti], kde se dozvíte vše potřebné. {{extras}}