Document the new choice list customization options

[xabbuh]

see symfony/symfony#14050 for more details and https://github.com/symfony/symfony/blob/2.7/src/Symfony/Component/Form/CHANGELOG.md and https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.7.md#form

• A) choice_list was deprecated, replaced with choices_as_values or choice_loader
• B) From UPGRADE-2.7.md: You should flip the keys and values of the "choices" option in ChoiceType and set the "choices_as_values" option to true. The default value of that option will be switched to true in Symfony 3.0. (I'm not sure what this actually means). There is also some new choice_value option - not sure how it relates.
• C) ChoiceListInterface namespace changed
• D) ChoiceView namespace changed AND order of arguments changed
• E) ChoiceList was deprecated in favor of DefaultChoiceListFactory
• F) property option of DoctrineType is now choice_label
• G) EntityChoiceList was deprecated, now use DoctrineChoiceLoader

[wouterj]

For the reference, there is a blog post about it on symfony.com: http://symfony.com/blog/new-in-symfony-2-7-choice-form-type-refactorization

And this has to be added to the choice type reference at least.

[weaverryan]

FYI - we should make this a priority. From what I hear, there may be some small gotchas with this refactoring, so we should play with it and update everyone so that when they come looking for docs after upgrading, we're ready :)

[weaverryan]

@wouterj @xabbuh I just summarized some of the changes as todos on this issue, mostly looking at the UPGRADE log: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.7.md#form. There are quite a few things actually, I'm going to do my best to get through some/all of these this week, but any help is appreciated (some may already be done in the docs, if they are, please check them off!)

[xabbuh]

@weaverryan Thank you for preparing this quite well! Can you please leave a comment here when you start to work on a particular topic? I have some time this weekend to work on this as well as finishing my pending pull requests and it would be bad if we did the same things twice. ;)

[weaverryan]

awesome - I will definitely do that!

[althaus]

Imho it's a pity that the docs are outdated with the stable release now. It's totally confusing and hard to sort out what's deprecated and what's the new way to do things correctly. :(

Especially the choices_as_values parameter does strange things. The "flip" thing also didn't work in my test case.

[weaverryan]

@althaus We try to do our best to keep up with everything, but we're just volunteers :). And yea, from looking at the new features, part of them look confusing - part of the reason I've got this high on my list.

@althaus if you figure any little things out that you think might help one of us when we document the options, please comment them here - it would be much appreciated!

[althaus]

@weaverryan I know that's all voluntary work and you're doing a great job. It's just sad, that such a big change is lacking the doc it'd need to be that great as it probably will be.

I'd be happy to contribute to the docs, but I'm still experimenting with the new options to get my desired results.

One thing so far taken from @webmozart blog post:

    'choices' => array(
        'Yes' => true,
        'No' => false,
        'Maybe' => null,
    ),

Perhaps it's just me, but that feels too constructed for me. Just to show what the new features can do. I never needed such a set of choices. Probably just me... ;-)

[althaus]

One issue showing a cause of confusion: symfony/symfony#14377

So at least I'm not alone on that part.

[davedevelopment]

Wow, just landed here after an hour or two digging through lots of code, PRs, UPGRADE files and now that blog post. Still have no idea how to proceed :)

[Th3Mouk]

I'm seeking since the 2.7.0 release any information on the choice_loader option but nobody on earth seems get it =)
I would appreciate to add a complete example on it, and how to make a personal database request on a entity field and DI.
Thanks so much.

[pylebecq]

The lack of documentation about this is becoming a serious issue.
Even the blog post seems outdated. The parameters received by the closures of these new options does not seem to correspond to the ones written in the blog post.

[weaverryan]

I agree - we've been way to slow on this. I'll make time this month, but a pull request from anyone who has experience with the new options is very welcome :)

[althaus]

@weaverryan I've worked quite a lot with the choices stuff and would be willing to do some docs... but most of the time it feels that I'm implementing workarounds to get (back) simple behaviour. So I never know if I'm doing something completely wrong or if @webmozart just thinks in more complex structures. Therefore I think only someone who really knows how the new choices (should) work can do the docs. Especially with the upcoming 3.0 release. :[

[weaverryan]

@althaus I haven't worked with the new choices yet, so I may be in the same situation as you :). I would definitely be interested if you started some of the changes (i.e. just updated the choice reference document) that gave examples of what you have found that works. I will see Bernhard next week, and if there is already a pull request by then, I can trick him into looking at it with me to answer those questions ;)

[althaus]

@weaverryan No, I haven't started anything yet. Just eagerly waiting for a form crack to jump in. I'm willing to give at least the reference a try and work in the changes from the blog post. That cannot become worse than the current situation.

[weaverryan]

@althaus anything you can do would be awesome! And I'll of course either get Bernhard or myself to double-check everything - no worries :). Thanks!

[althaus]

@weaverryan I've started to implement the basics based on all the information (*) I could found in my fork. As there are some major changes, I'd probably will need some help about correct formatting and usage of tip/caution/deprecated blocks.

Is there an easy way that I can render that part of the doc as HTML to check the output from the structured text?

(*) taken from:
symfony/symfony#14050
https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.7.md#form
http://symfony.com/blog/new-in-symfony-2-7-choice-form-type-refactorization

[wouterj]

@althaus please create a pull request (and prefix the title with [WIP], meaning Work In Progress). That's a lot easier to review and you get a complete HTML render automatically from platform.sh: http://symfony.com/blog/how-we-auto-deploy-documentation-pull-requests-with-platform-sh

[althaus]

@wouterj Oh cheers... didn't read the contribution page far enough. Perhaps the "Review your changes" part should be mentioned earlier in the guide. ;-)

#5847 is up and waits for the build. Will check later what's the result of it.

[althaus]

@wouterj Shouldn't PRs against 2.7 get build automatically? I cannot see platform.sh hooking into my PR. :(

[xabbuh]

@althaus It sometimes takes some time. But you should be able to see it now.

[weaverryan]

I've just merged the documentation that covers "most" of this - #5876, though it only checks off a few items.

I think most of the other items are "easy" - someone just needs to check if we're using old namespaces anywhere, etc. The only one that's still interesting is the first: choice_loader. I don't understand the use-case for this? @Th3Mouk mentioned using it to query for some entities, but I would just do that with the entity type, or inject whatever services I need into my form, fetch the stuff I need, then put them into the choices field. Why should someone use choice_loader?