Requirements
The product page needs to include variation fields. The product and variation fields can be mixed / interleaved, there is no clear boundary between them.
Changing the variation on the add to cart form should replace the previously rendered variation fields.
There are two different roles customizing product display:
1) Themer
Uses twig to create a layout by hand.
Needs access to the individual product and variation fields in the twig file.
2) Site builder
Uses Display Suite or Panels to add fields to a premade layout (provided by layout_plugin).
Needs access to the variation fields in the relevant UI.
Commerce 1.x
Field injection was implemented via hook_field_extra_fields, giving a node the commerce_product fields. Any field marked as "Visible" would be injected.
While it provided a solution, it was often confusing and difficult:
- Controlling the theming seemed difficult
- The formatter and other settings for commerce_product fields had to be selected on the Manage display screen for products, resulting in back & forth between two different Manage display screens, both with their own weights
Proposed resolution: Themer
We start here.
1) Create a service that returns variation fields that are candidates for injection.
From base fields this includes only 'sku' and 'title' . From configurable fields this includes all non-attribute fields. We don't need attribute fields cause they're already managed by the attribute selection widget.
2) Add a method to ProductInterface for fetching the default variation
This is currently implicit (we get delta 0), so let's make it explicit.
3) Add an "Inject product variation fields into the rendered product" to the product type.
4) In a template preprocess function, load the product type, check the setting, if TRUE get the fields for injection.
Then load the default variation and render the fields.
This field rendering probably belongs in the same service that gets the candidate fields.
Behind the scenes, each field is rendered via $view_builder->viewField($entity->{$field_name}, $product_view_mode).
The fields are then passed to Twig for rendering, keyed by 'variation_'. For example 'variation_sku'. The twig template should document this.
5) Ensure that rendered fields have a class we can target on ajax. See quickedit_preprocess_field() for an example.
6) On #ajax get the new variation, rerender the fields, return the ajax commands that replace the previous fields.
That's it. The themer gets full control, needs to use two different manage field screens for configuring settings (just like in 1.x).
Proposed resolution: Site builder
This requires that we first implement the themer solution, cause the #1, #2, #5 and #6 parts are the same.
The site builder turns off field injection on the product type, then uses DS or Panels.
Panels doesn't support relationships yet. Once it does, the user will be able to add a variation relationship, add the individual fields, configure the formatter and other settings. We just need to ensure that the relationship is there.
For DS we implement a derivative DsField plugin that provides a plugin definition for each field injection candidate, then renders and returns it. Since DsField plugins can have settings, we can ask for the formatter and settings here, and pass them along to $view_builder->viewField() instead of the view display id.