[Form] Added documentation for Form Events #3704

csarrazi · 2014-03-21T16:39:56Z

Q	A
Doc fix?	no
New docs?	yes
Applies to	>=2.3
Fixed tickets	Dunno

Added initial documentation for Form Events:

List of events
Use cases for each event
Description of the events workflow
Flow charts for illustration
Registering event listeners or subscribers in a form
Describing the data available for each event

csarrazi · 2014-03-21T16:42:51Z

This is an initial WIP. It is far from being finished, but the final goal is to completely describe Form Events in the component's documentation, and not only in the cookbook, which doesn't formally explains form events.

wouterj · 2014-03-21T16:44:48Z

Wow, thank you!

Please note that there is already an article about form events in the cookbook: http://symfony.com/doc/current/cookbook/form/dynamic_form_modification.html You might be able to get some usefull things from it. At least, you should remove all things you put in the components article from that cookbook article and add a reference (or multiple references) to this new article.

In the end, we should have a components article telling you everything you need to know about Form Events and a cookbook article which gives you a short introduction and framework specific things. If you do not want to do this, someone of the community can do it after this one is merged. :)

Again, big thanks for getting this roling!

wouterj · 2014-03-21T16:45:21Z

components/form/form_events.rst

+    The Form component provides a structured process letting you customize your
+    forms, by making use of the EventDispatcher. Using form events, you may
+    modify information or fields at different points of time. From the form's
+    pre-population to the submission of the request's data.


This should not be indented (that something specific for the component introduction articles, I don't know why we did that...)

csarrazi · 2014-03-21T23:55:22Z

Done. Also added a bit of code for adding a form event listener and a form event subscriber when using the form builder.

cordoval · 2014-03-22T03:04:20Z

components/form/form_events.rst

+Form Events
+===========
+
+The Form component provides a structured process letting you customize your


to let you customize

xabbuh · 2014-03-22T09:42:06Z

👍 Great article! I really like it!

wouterj · 2014-03-22T09:48:17Z

components/form/form_events.rst

+
+The ``PRE_SET_DATA`` event is dispatched when
+:method:`Form::setData() <Symfony\\Component\\Form\\Form::setData>`
+is called. It can be used to:


this is somewhat duplicating the previous paragraph. I think we have to tell when it happends, like: "The PRE_SET_DATA event is dispatched in the beginning of the Form::setData() method."

stof · 2014-03-24T10:22:34Z

components/form/form_events.rst

+
+The ``SUBMIT`` event is dispatched just before the
+:method:`Form::submit() <Symfony\\Component\\Form\\Form::submit>` method
+transforms back the normalized data to the model and view data.


this is wrong. the normalized data is not transformed back to the view data, as it was just build from the submitted view data

Actually, it is. See https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Form.php#L632

// Synchronize representations - must not change the content! $modelData = $this->normToModel($normData); $viewData = $this->normToView($normData);

csarrazi · 2014-03-25T19:02:43Z

Rebased commits once again.

weaverryan · 2014-03-26T22:24:15Z

WOW, this is really incredible! Great great work!

I have one thought. There are basically 2 sections to this entry: (A) explaining the form lifecycle and different events and (B) how to actually register event listeners/subscribers. I think we should change their order: explain how to register listeners first, then explain the event second.

The reason is that I realized in the beginning (where we talk about the different events), we're talking about how to get at form data and the event object, as well as referring to events simply as SUBMIT, before really explaining that these are constants on FormEvents. If you reverse the order of these sections, I think it's an even better entry.

What do you guys think? After this issue (and I left one other small comment), this is ready to merge! Great work to everyone!

csarrazi · 2014-03-26T22:40:13Z

Hum, not sure. I just made the change locally, and it actually feels weird talking about form event listeners and subscribers before actually describing the events and the workflow. If we invert the sections, we need to rephrase a few things so it feels fluid.
In any case, I can also rephrase the sections of the documentation to refer to FormEvents::{EVENT_NAME} instead of simply {EVENT_NAME}.

weaverryan · 2014-03-26T22:47:39Z

Ok, let's keep it how it is - but yea, I like FormEvents::{EVENT_NAME} better, and we can also add a quick note to the top with a link that points to the second section on usage. A very very quick example usage at the top of the chapter (not really doing anything, just showing the registration of an anonymous function on some form event, and the arguments of that callback) might be plenty to give people enough idea of how this works before explaining the events.

Thanks for checking it out :)

csarrazi · 2014-03-30T18:42:56Z

Done. And also rebased the commits.

csarrazi · 2014-04-01T19:58:18Z

Well then, I guess it should be ready for merge, now!
What do you think about it now, @weaverryan? :)

xabbuh · 2014-04-02T09:13:58Z

components/form/form_events.rst

+    validate the CSRF token.
+
+B) The ``FormEvents::SUBMIT`` Event
+.......................


The underline doesn't match the title length.

csarrazi · 2014-04-05T10:33:44Z

Updated

csarrazi · 2014-04-05T21:33:56Z

Fixed issue with travis build (underline too short)

csarrazi · 2014-04-08T10:04:37Z

ping @weaverryan

wouterj · 2014-04-08T12:23:12Z

@csarrazi this PR is now ready. It'll be merged once @weaverryan has time to review and merge it. Since this PR add lots of stuff, it can take a little bit longer than smaller PRs. But don't worry, this great PR will never be missed by us :)

xabbuh · 2014-04-08T12:49:54Z

@csarrazi But you can remove the [WIP] tag from the title for now. So, it's more obvious that the PR is finished. :)

csarrazi · 2014-04-08T13:38:47Z

Thanks! I removed the [WIP] tag :)

gilles-g · 2014-04-22T14:19:31Z

components/form/form_events.rst

+    use Symfony\Component\Form\FormEvent;
+    use Symfony\Component\Form\FormEvents;
+
+    class AddEmailFieldListener implements EventSubscriberInterface


Maybe change the name to AddEmailFieldSubscriber

Using listener for this is a Symfony convention, so let's stick with it (although I tend to agree with you that Subscriber is a better naming)

csarrazi · 2014-04-30T14:51:02Z

bump @weaverryan ! :)

aitboudad · 2014-05-01T19:16:08Z

components/form/form_events.rst

+different steps of the workflow: from the population of the form to the
+submission of the data from the request.
+
+Registering an event listener very easy using the Form component.


is very easy

aitboudad · 2014-05-01T21:33:47Z

👍

@wouterj

Added initial documentation for Form Events: * List of events * Use cases for each event * Description of the events workflow * Flow charts for illustration Updated PR with comments from @wouterj and @mykiwi Took into account @cordoval's feedback Additional improvements * Added more examples from the Form component's code * Moved the cookbook's 'register a subscriber using a callable' section into the form events documentation Took into account @xabbuh's feedback Fixed missing new line Removed superfluous comma. Updated from feedback Moved the list of events down in the listener and subscriber section * Formatted the list as a table, exposing the constant values; * Added references to the form event information table; * Added caution sections for actions that should prevented while in each event. Added the form_events link in the components map file, a.k.a. 'Added the missing link' Added missing newlines Added cross-reference in the form events cookbook Updated based on Luis' feedback Added tables describing the form and event values: * Model data * Normalized data * View data * Event data Small fixes Updated a few wordings to make them more clear Changed important directive to caution Removed sidebar section about form extensions. Renamed ``{EVENT}`` to ``FormEvents::{EVENT}``, and added code snippet Last small changes Fixed underline too short

weaverryan · 2014-05-06T12:01:48Z

Sorry for getting the merge slowly - this is a truly wonderful effort and entry. I'm looking forward to showing this resource to people who are working with form events. Great work to you Charles and everyone :). Thanks!

This PR was merged into the 2.3 branch. Discussion ---------- [Form] Added documentation for Form Events | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | >=2.3 | Fixed tickets | Dunno Added initial documentation for Form Events: * List of events * Use cases for each event * Description of the events workflow * Flow charts for illustration * Registering event listeners or subscribers in a form * Describing the data available for each event Commits ------- 98de95a [Form] Added documentation for Form Events

wouterj reviewed Mar 21, 2014
View reviewed changes

cordoval reviewed Mar 22, 2014
View reviewed changes

wouterj reviewed Mar 22, 2014
View reviewed changes

stof reviewed Mar 24, 2014
View reviewed changes

xabbuh reviewed Apr 2, 2014
View reviewed changes

csarrazi changed the title ~~[WIP] [Form] Added documentation for Form Events~~ [Form] Added documentation for Form Events Apr 8, 2014

gilles-g reviewed Apr 22, 2014
View reviewed changes

aitboudad reviewed May 1, 2014
View reviewed changes

weaverryan merged commit 98de95a into symfony:2.3 May 6, 2014

csarrazi deleted the components/form/form_events branch May 6, 2014 12:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Form] Added documentation for Form Events #3704

[Form] Added documentation for Form Events #3704

csarrazi commented Mar 21, 2014

csarrazi commented Mar 21, 2014

wouterj commented Mar 21, 2014

wouterj Mar 21, 2014

csarrazi commented Mar 21, 2014

cordoval Mar 22, 2014

xabbuh commented Mar 22, 2014

wouterj Mar 22, 2014

stof Mar 24, 2014

csarrazi Mar 24, 2014

csarrazi commented Mar 25, 2014

weaverryan commented Mar 26, 2014

csarrazi commented Mar 26, 2014

weaverryan commented Mar 26, 2014

csarrazi commented Mar 30, 2014

csarrazi commented Apr 1, 2014

xabbuh Apr 2, 2014

csarrazi commented Apr 5, 2014

csarrazi commented Apr 5, 2014

csarrazi commented Apr 8, 2014

wouterj commented Apr 8, 2014

xabbuh commented Apr 8, 2014

csarrazi commented Apr 8, 2014

gilles-g Apr 22, 2014

wouterj Apr 22, 2014

csarrazi commented Apr 30, 2014

aitboudad May 1, 2014

aitboudad commented May 1, 2014

weaverryan commented May 6, 2014

[Form] Added documentation for Form Events #3704

[Form] Added documentation for Form Events #3704

Conversation

csarrazi commented Mar 21, 2014

csarrazi commented Mar 21, 2014

wouterj commented Mar 21, 2014

Choose a reason for hiding this comment

csarrazi commented Mar 21, 2014

Choose a reason for hiding this comment

xabbuh commented Mar 22, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csarrazi commented Mar 25, 2014

weaverryan commented Mar 26, 2014

csarrazi commented Mar 26, 2014

weaverryan commented Mar 26, 2014

csarrazi commented Mar 30, 2014

csarrazi commented Apr 1, 2014

Choose a reason for hiding this comment

csarrazi commented Apr 5, 2014

csarrazi commented Apr 5, 2014

csarrazi commented Apr 8, 2014

wouterj commented Apr 8, 2014

xabbuh commented Apr 8, 2014

csarrazi commented Apr 8, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csarrazi commented Apr 30, 2014

Choose a reason for hiding this comment

aitboudad commented May 1, 2014

weaverryan commented May 6, 2014