Better documentation for customize a Collection Prototype

http://symfony.com/doc/master/cookbook/form/form_customization.html#how-to-customize-a-collection-prototype

There is a form field named tasks. But why is the form field (in the block) named task?

For example I have a form field named externalIds. Would the form in the block named externalId?
If yes: Why? Magic?

How to customize a Collection Prototype if the form field is named externalIds? What is the correct name of the block?

Already tried:

• _externalIds_entry_widget
• _external_ids_entry_widget
• _external_id_entry_widget
• externalIds_entry_widget
• externalId_entry_widget
• external_Ids_entry_widget
• external_id_entry_widget

[wouterj]

I don't see a block named task in the section about overriding the collection prototype.

{% block _tasks_entry_widget %}
    <tr>
        <td>{{ form_widget(task.task) }}</td>
        <td>{{ form_widget(task.dueDate) }}</td>
    </tr>
{% endblock %}

I mean task.task and task.dueDate. Why task? Where does it come from?

The block itself is named _tasks_entry_widget because the form field is tasks.

I don't get it working with a form field named externalId. What is the correct name of the block?

That because I think the documentation about this should be better.
Everybody should easily understand it.

[toomoi]

I totally agree with you. I read this documentation again and again, but no way to exploit it.. I'm trying to use Macros to reach my goal, but I am convinced that there is a solution provided by symfony...

I've found out how it works. You need to add the name of the form as prefix.

As example:

{% block _new_sms_recipientNumbers_entry_widget %}
{# ... #}
{% endblock %}

The form type class name is NewSmsType - that because _new_sms_ is important as prefix.

The collection type is named recipientNumbers:

$builder->add('recipientNumbers', CollectionType::class);

Now I need the inner variable names. recipientNumber is not working.

I found a way to get all available variables in a block to understand what is possible:

{% block _new_sms_recipientNumbers_entry_widget %}
    {{ dump() }}
{% endblock %}

[Vatvat99]

I am also having difficulties to understand that part of documentation.

The doc shows:

{% form_theme form _self %}

{% block _tasks_entry_widget %}
    <tr>
        <td>{{ form_widget(form.task) }}</td>
        <td>{{ form_widget(form.dueDate) }}</td>
    </tr>
{% endblock %}

I don't understand where does {{ form_widget(form.task) }} and {{ form_widget(form.dueDate) }} are coming from ?

In my case, I have a field offer_pictures that I display like this in my template:

{% block content %}
    {{ form_start(form) }}
    {{ form_widget(form.offer_pictures) }}
    {{ form_end(form) }}
{% endblock %}

If I try to customize the placeholder like that:

{% form_theme form _self %}

{% block _offer_offer_pictures_entry_widget %}
        {{ form_widget(form.offer_pictures) }}
{% endblock %}

Symfony returns this error : Method "offer_pictures" for object "Symfony\Component\Form\FormView" does not exist in :offer:add.html.twig at line 16

Don't we have access to form fields in the entry_widget block ? As I understand it, that's what the doc suggests.

@Vatvat99 Could you show us your form class and entity fields?

[xabbuh]

In this block you have access to the fields of the Form type that you embedded in the collection type. offer_pictures seems to be your collection and not the embedded type.

@Vatvat99 You should try out this code:

{% block _offer_offer_pictures_entry_widget %}
        {{ dump() }}
{% endblock %}

This will provide you a lot of information thanks to the VarDumper Component.

[HeahDude]

@Vatvat99 in the block of your example form is the entry so you can only access fields of one offer_picture field. As suggested by @JHGitty {{ dump(form) }} should help.

@JHGitty if you have a collection field with a name externalIds, its default block name is the same then you have access to _externalIds_widget and _externalIds_entry_widget.

You can customize the block name only (without modifying the field's name) with the option block_name.
If the entry is also a collection you may have a scenario like this:

class TaskManagerType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options = array())
    {
        // ...
        $builder->add('taskLists', CollectionType::class, array(
            'entry_type' => TaskListType::class,
            'block_name' => 'task_lists',
        ));
    }
}

class TaskListType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options = array())
    {
        // ...
        $builder->add('tasks', CollectionType::class, array(
            'entry_type' => TaskType::class,
        ));
    }
}

class TaskType
{
    public function buildForm(FormBuilderInterface $builder, array $options = array())
    {
        $builder->add('name');
        // ...
    }
}

Leading to the lines below in a controller:

// ...
$form = $this->createFormBuilder(TaskManagerType::class)
    ->add('Save', SubmitType::class)
    ->getForm();
// ...
return $this->render('/form.html.twig', array('form' => $form->createView()));

Then you get the following customizable blocks (* is standing for "row", "widget", or "label"):

{% block _task_manager_task_lists_* %}{# the collection field of TaskManager #}
{% block _task_manager_task_lists_entry_* %}{# the inner TaskListType #}
{% block _task_manager_task_lists_entry_tasks_* %}{# the collection field of TaskListType #}
{% block _task_manager_task_lists_entry_tasks_entry_* %}{# the inner TaskType #}
{% block _task_manager_task_lists_entry_tasks_entry_name_* %}{# the field of TaskType #}

Hope that helps.

@HeahDude Do you like to optimize the documentation about this?

[HeahDude]

@JHGitty Do you mean if I'm in favor of some changes or if I should try to send a PR myself?

First, definitely yes, the example provided in http://symfony.com/doc/master/cookbook/form/form_customization.html#how-to-customize-a-collection-prototype looks clearly inconsistent.

I think there is already some work in progress in #6321. Maybe you should give some feedback there to get it moving forward.

[Vatvat99]

@JHGitty @HeahDude @xabbuh Thanks for your help, and sorry for taking time to respond. Indeed, as xabbuh said, I can only access to the fields of the FormType, not the FormType itself.