Rozšiřování článku v dokumentaci
- Filip Procházka
- Moderator | 4668
Článek https://doc.nette.org/cs/forms?… je krásná ukázka, jak nám kyne těsto. V tomhle případě máčka. Samozřejmě jakoukoliv aktivitu ohledně dokumentace chválím a jenom velmi nerad bych v přispěvatelích udusil nadšení a zápal cokoliv psát nebo opravovat.
Ale potřeba rozlišovat, jestli to co píšeme, už není trochu moc omáčky. Informace přidané v revizích 14,15 a 16 podle mě patří do wiki.
Pokud založíš článek, nebo to přidáš někam do FAQ tak to bude mnohem lepší. Už tak je článek o formulářích přespříliš dlouhý a bylo by vhodné jej rozdělit, místo nabalování dalších informací.
Rozlišujme proto prosím vývojářskou wiki a dokumentaci.
- Filip Procházka
- Moderator | 4668
Článek jsem opravil. Změny dokonce lehce měnily funkčnost formulářů a mohly by tak vznikat neočekávané výsledky :P
Editoval HosipLan (31. 8. 2011 13:55)
- petr.pavel
- Člen | 535
HosipLana jsem kontaktoval e-mailem a svoje důvody mu vysvětlil. Vzájemně
jsme se nepřesvědčili :-)
Kdyby někoho zajímaly moje argumenty, rád pošlu.
- Filip Procházka
- Moderator | 4668
Petře, pokud chceš, můžeš sem do fóra zkopírovat ty emaily. Aspoň si to přečte kdo chce, pokud ho to bude zajímat, ne?
- petr.pavel
- Člen | 535
Máš recht, posbíráme názory ostatních. Můj první e-mail HosipLanovi:
Ahoj Filipe, díky za opravy chyb callbacku. Souhlasím i s odstraněním té opakované metody signInFormSubmitted. Ale nesouhlasím s odstraněním příkladu se (1) setAction a (2) skrytým políčkem pro GET.
Jestli (1) není dost Nette-way, tak bys tedy můj kód měl nahradit svým, který Nette-way je. Ne ho zrušit úplně. Mazat umí každý. Potřeba odesílat formulář jinam je velmi častá, jen se podívej, kolikrát se to protřepávalo ve fóru. Zpracovávat odeslaný formulář v komponentě není vhodné vždy. Skutečnost, že to Nette nepodporuje „čistě“ přeci neznamená, že budeme strkat hlavu do písku a nechávat uživatele, aby si to „nečisté“ řešení pořád dokola objevovali sami.
Co se týče (2): Nejsou mi jasné důvody, proč už někdo do makra form to skryté políčko nedodělal, tenhle boj nechávám ostatním. Než se to ale nějak vyřeší čistě, nemůžeme zase strkat hlavu do písku a předstírat, že něco funguje, když to není pravda. Taky se to kolikrát probíralo ve fóru, dokumentace by se k tomu měla nějak vyjádřit. I kdyby tam mělo být „Formulář odesílaný přes GET není možné ručně vykreslovat“. Uvědomuješ si ale absurditu takového tvrzení? Jak nejde?!
Mohl bys tedy do dokumentace doplnit jiný text, který obě oblasti pokrývá čistým způsobem?
Díky
Petr
- petr.pavel
- Člen | 535
HosipLanova odpověď:
Ahoj,
pokud potřebuješ posílat formulář jinam, než na aktuální akci, pak máš možnost použít Nette\Forms\Form místo Nette\Application\UI\Form. A tomu si nastavit jinou akci. Posílat ale formulář na signál jiného presenteru je špatně. Signál totiž mění stav aktuálního presenteru.
Co se týče GET formulářů, pak řešením je použít klasický renderer formulářů. Formulářová makra jsou prostě řeší mnohem méně věcí.
Jak už jsem zmiňoval, věci co jsi napsal k formulářům patří do wiki.
S pozdravem
Filip
Editoval petr.pavel (31. 8. 2011 15:37)
- petr.pavel
- Člen | 535
Moje odpověď:
Díky za vysvětlení.
Co když ale potřebuji měnit stav toho cílového presenteru. Příklad: vyhledávací formulář zakázek po odeslání v zakazkySubmitted() odfiltruje některé zakázky a výsledek uloží do $this->zakazky. V renderSearch se pak jen výsledek předá šabloně. A ten vyhledávací formulář potřebuji zobrazit na každé stránce.
Nedokážu si přesně představit to řešení s Nette\Forms\Form, kde
k němu najdu nějaké příklady a dokumentaci? doc:forms je v tomto ohledu
dost skoupé.
Znamenalo by to, že bych nadále v továrničce nastavoval přes setAction,
akorát bez parametru „do“, a pak v presenteru zakázek v renderSearch
bych odeslané hodnoty bral z $httpRequest->getPost() a filtroval
v renderSearch? Jak bych takový formulář vykresloval v šabloně
presenteru?
GET formuláře: Tak to do té dokumentace napiš. Takhle nemá uživatel důvod si myslet, že by GET neměl fungovat a POST jo. Osobně mi to ale přijde nesmyslné, makro form by mělo fungovat pro obě metody a měli bychom nabídnout workaround, dokud tomu tak nebude.
Nepatří do dokumentace, ale do „wiki“: Tím myslíš Kuchařku?
Říkáš „jak už jsem zmiňoval“ – asi jsem to neviděl, kam's to
prosím psal?
Osobně asi vidím hranici mezi „dokumentací s příklady“ a
„řešení častých situací“ jinde, ale tady se těžko argumentuje.
Podle mě je rozhodující, jak často se lidi na něco ptají ve fóru. Když
je to častá začátečnická otázka, tak patří příklad do dokumentace.
Jestli je to specialitka, tak do Kuchařky.
Asi se bojíš, aby stránka Formuláře moc nebobtnala. Není ale správné vynechávat informace důležité pro začátečníky. To už raději rozdělit na dvě stránky.
Petr
- petr.pavel
- Člen | 535
HosipLanova odpověď:
Co když ale potřebuji měnit stav toho cílového presenteru.
- to je ale logicky hloupost. Na stav můžeš odkázat tak, že pošleš správné parametry v odkazu. Né tak, že vygeneruješ signál s parametry.
Nedokážu si přesně představit to řešení s Nette\Forms\Form, kde k němu najdu nějaké příklady a dokumentaci?
- posílat cokoliv na jiný presenter je obecně hloupost. Lepší je poslat to na aktuální, uložit do session nebo databáze a pak přesměrovat a načíst si stav na druhém presenteru z databáze.
- ale jinak ano, chováš se k tomu jako k UI\Form, nastavíš
akci
->setAction($this->link('Presenter:akce'));
GET formuláře: Tak to do té dokumentace napiš.
- smysl to možná nedává, ale je to tak a David má prostě prázdniny. Pošli pull na github a urguj změny.
Nepatří do dokumentace, ale do „wiki“: Tím myslíš Kuchařku?
- třeba, ale spíše obecně nějaká stránka, nalinkovat ji můžeš z kuchařky nebo z FAQ
Říkáš „jak už jsem zmiňoval“ – asi jsem to neviděl, kam's to prosím psal?
- psal jsem zde: https://forum.nette.org/…-dokumentaci
Osobně asi vidím hranici mezi „dokumentací s příklady“ a „řešení častých situací“ jinde, ale tady se těžko argumentuje.
- vskutku, „balancuje to na ostří nože“
Podle mě je rozhodující, jak často se lidi na něco ptají ve fóru.
- to není dobrý faktor. Na věci, na které se lidé často ptají z principu pasuje „Frequently asked questions“ :)
Asi se bojíš, aby stránka Formuláře moc nebobtnala. Není ale správné vynechávat informace důležité pro začátečníky. To už raději rozdělit na dvě stránky.
- což jsem psal v tom tématu, které mi bylo jasné, že přehlédneš. Doporučil bych ti odebírat RSS celého fóra.
- Patrik Votoček
- Člen | 2221
- petr.pavel
- Člen | 535
Nikdo jiný se nevyjádřil, tak bych rád ještě shrnul nejdůležitější části mých námitek pro HosipLanovým důvodům smazat můj text:
- Umístění
Je mi jedno, jestli ve wiki, docs nebo některém z mnoha jiných zdrojů
informací o Nette (podle mě jich je až moc), ale někde by být měly.
Jestli jsem zvolil špatné místo, měl to HosipLan přesunout, ne smazat.
Mimochodem, už sama existence stránek typu FAQ znamená, že je něco
špatně. Když se lidi často ptají na to samé, tak jsem to buď blbě
navrhnul nebo blbě vysvětlil. Nemá smysl založit Ještě Další Stránku,
kde budu něco vysvětlovat. To je jako vyvěsit
na nástěnku informaci o zbourání Zeměkoule.
- Čistota
Jestli to nebylo dost čisté, měl to HosipLan změnit na čistší, ne smazat. Jestli čisté řešení neexistuje, tak měl nechat „špinavé“ do té doby, než bude čisté k dispozici.
Kdosi ve fóru poznamenal, že aby člověk pronikl do Nette, musí přečíst celé fórum. Naprosto souhlasím a považuji to za základní nedostatek Nette.
Editoval petr.pavel (4. 9. 2011 16:11)
- Ondřej Brejla
- Člen | 746
Mě spíš udivuje, že na tvoje posty vůbec někdo reaguje :-)
A abych nebyl tak úplně OT, tak tvá vyjádření typu „Mimochodem, už sama existence stránek typu FAQ znamená, že je něco špatně.“ mi přijdou minimálně dosti svérázná, spíš zcestná a poměrně naivní.
Nicméně držím palce, aby si se Nette bez nějaké větší újmy naučil :-)
- Filip Procházka
- Moderator | 4668
podle mě jich je až moc
Naopak, jejich vytvoření předcházely dlouhé debaty o tom, kam co patří a „wiki“ je svou podstatou dokumentace od vývojářů.
měl to HosipLan přesunout, ne smazat.
V konečném důsledku jsem smazal jenom ty dva příklady s tím odkazováním. Zbytek jsem zkrátil, nebo přepsal.
Mimochodem, už sama existence stránek typu FAQ znamená, že je něco špatně. Když se lidi často ptají na to samé, tak jsem to buď blbě navrhnul nebo blbě vysvětlil.
Ne. To znamená, že někteří jsou tak hloupí a nesamostatní, že nejsou schopní si ani načíst dokumentaci. Nebo je odpověď tak prostá, že se na samostatný článek nehodí a plnit s ní, k prasknutí plné, články v dokumentaci není na místě.
Jestli čisté řešení neexistuje, tak měl nechat „špinavé“ do té doby, než bude čisté k dispozici.
S tímhle zásadně nesouhlasím. Někteří jsou schopni brát to co je v dokumentaci jako zákon. Takové lidi se pak špatně přeučuje. Navíc, nikoho jiného to kromě tebe netrápí.
Příklad se změnou action formuláře nebudeme počítat, protože to samo o sobě odporuje Nette a řešení jsem ti napsal.
Co se týče toho GET formuláře. Takové formuláře se používají
typicky na ovlivňování stavu nadřazené komponenty. Takže třeba takové
vyhledávání. Formulář posílá parametr query, který si
přečte presenter a přizpůsobí požadavky hledání. Nebo filtrace gridu, to
stejné. Téma by možná obsáhlo samostatný článek.
Nevidím důvod, proč by tvoje konkrétní použití mělo být v dokumentaci. Maximálně tak ve wiki, jako alternativa. Navíc tvůj příklad použití GET formuláře považuji za špatný.
Kdosi ve fóru poznamenal, že aby člověk pronikl do Nette, musí přečíst celé fórum. Naprosto souhlasím a považuji to za základní nedostatek Nette.
Což platilo, když byla dokumentace zastaralá. Teď už to neplatí.
- smasty
- Člen | 90
petr.pavel wrote:
Mimochodem, už sama existence stránek typu FAQ znamená, že je něco špatně.
Takže chceš poprieť význam stránky, ktorá je súčasťou väčšiny webových stránok, pravdepodobne od vzniku World Wide Webu? Keby tá stránka nemala význam, už roky by sa nepoužívala.
Naopak, to, že ju nájdeš tamer na každej webstránke znamená, že je to rokmi overený postup, ktorý je užitočný a prínosný.
Kdosi ve fóru poznamenal, že aby člověk pronikl do Nette, musí přečíst celé fórum.
To platilo, kým tu bola stará dokumentácia. V súčasnej podobe je
dokumentácia plne dostačujúca, skôr má teraz opačný problém – sem-tam
sa nájde niečo, čo ešte v skutočnosti nie je implementované. (napr.:
n:input).
Naprosto souhlasím a považuji to za základní nedostatek Nette.
Ja osobne za jediný nedostatok Nette považujem jeho slabú rozšírenosť v zahraničí. Preto sm sa zapojil aj do prekladu dokumentácie, aby som aspoň trochu pomohol.
Ae to už sme trochu off-topic…
- David Grudl
- Nette Core | 8218
Jen pár poznámek: dokumentace bych měla být pokud možno co nejobsáhlejší a zároveň nejstručnější. Ano, ty dvě věci jdou proti sobě, proto je třeba hledat kompromis.
Vše, co se objeví v dokumentaci, se „legalizuje“ a stává návodem. Proto se tam nemůžou objevit nečisté nebo nepodporované techniky, natož hacky. Pokud jsou skutečně potřeba, je lepší o tom otevřít diskusi. To je třeba případ formuláře vedoucího na jiný presenter.
Kód v dokumentaci musí být odzkoušený a nesmí obsahovat nic zbytečného. Co jsem zaznamenal ve zmíněných revizích, třeba callback() na protected metodu nebude fungovat, předávání $parent a $name v továrničce je zbytečné, použití Html::el v šabloně proti smyslu Latte atd.
Jsem velmi rád, že se na tvorbě dokumentace podílíte. Pokud nemáte 100% jistotu, jestli tam něco dát, je lepší to prvně umísit na wiki a poté třeba přesunout do dokumentace.