CustomElementProcessorWithKeyInterface added; standard processors implement it.

A new interface CustomElementProcessorWithKeyInterface extends the addtoElement() method signature with an optional fourth argument:

   * @param string $key
   *    (Optional) Name to use for adding data into (a slot / attribute in) the 
   *    custom element. Processors can use this how they see fit. Most use it
   *    as a literal key value; some may use it as e.g. a key prefix to add
   *    several values.

Also, CustomElementGenerator::process() (i.e. the method in the custom_elements.generator service) has had this same argument added.

Processors should implement the new interface if they want to be fully usable with new Custom Elements Displays. More precisely:

• The 'name' property for all fields defined in a "entity_ce_display" entity can be defined in configuration and in the Custom Elements Ui.
• If an 'Auto' formatter is set for any field, it can use Processors.
• The configured name gets passed through the $key argument, so processors are encouraged to use that configurable name if there's any chance they will be used by an "Auto" formatter.

Compatibility / breakage

Custom processor classes which are extending a processor shipped with the module, must update the addtoElement() method signature to include the new argument, before updating to a 3.x version. With this extension, processors are compatible with both 2.x and 3.x versions.

Both interfaces will keep existing for the foreseeable future (given there is no good way of deprecating CustomElementProcessorInterface).

Example change

Before:

class Custom implements CustomElementProcessorInterface {

  public function addtoElement($data, CustomElement $element, $viewMode) {
    // Possible code: $name / $derived_data derived from somewhere.
    ...
    $element->setAttribute($name, $derived_data);
    // Or e.g.
    $nested_element = new CustomElement();
    $this->getCustomElementGenerator()->process($derived_data, $nested_element, $viewMode);

After:

// If you are still on v2: keep the old "implements" and change it later:
class Custom implements CustomElementProcessorInterface {
// If you are already on v3:
class Custom implements CustomElementProcessorWithKeyInterface {

  public function addtoElement($data, CustomElement $element, $viewMode, $key = '') {
    ...
    $element->setAttribute($key ?: $default_name, $derived_data);
    // Or e.g.
    $nested_element = new CustomElement();
    $this->getCustomElementGenerator()->process($derived_data, $nested_element, $viewMode, $key);