Tidy source contexts

Problem/Motivation

Interesting stuff is happening on Display Builder side: #3579299: Tidy context management which can inspire us to clean the context on UI Patterns side.

UI Patterns has a very specific way of dealing with contexts:

• Derivable context plugin type:
  • src/Attribute/DerivableContext.php
  • src/DerivableContextInterface.php
  • src/DerivableContextPluginBase.php
  • src/DerivableContextPluginManager.php (and the related plugin.manager.ui_patterns_derivable_context service)
  • src/EventSubscriber/UiPatternsEntitySchemaSubscriber.php (and the related ui_patterns.entity_schema_subscriber service)
  • src/Plugin/Derivative/DerivableContextDeriver.php
  • src/Plugin/UiPatterns/DerivableContext/EntityFieldDerivableContext.php
  • src/Plugin/UiPatterns/DerivableContext/EntityReferencedDerivableContext.php
• Requirements context plugin:
  • src/Plugin/Context/RequirementsContext.php
  • src/Plugin/Context/RequirementsContextDefinition.php
  • the attribute in \Drupal\ui_patterns\Attribute\Source
• Resolvers:
  • src/Resolver/ChainContextEntityResolver.php (and the related ui_patterns.chain_context_entity_resolver service)
  • src/Resolver/ChainContextEntityResolverInterface.php
  • src/Resolver/ContextEntityResolverInterface.php
  • src/Resolver/FieldLayoutContextEntityResolver.php
  • src/Resolver/LayoutBuilderContextEntityResolver.php
  • tests/src/Kernel/Resolver/ChainContextEntityResolverTest.php
• A specific constraint plugin used in ComponentFormatter:
  • src/Plugin/Validation/Constraint/RequiredArrayValuesConstraint.php
  • src/Plugin/Validation/Constraint/RequiredArrayValuesConstraintValidator.php
• A trait used by SourcePluginManager:
  • src/ContextMatcherPluginManagerInterface.php
  • src/ContextMatcherPluginManagerTrait.php
• and maybe more...

The main part of this mechanism is the context_requirements attributes which has been added because Core's ContextAwarePluginManagerTrait::getDefinitionsForContexts() (which is the reference implementation of ContextAwarePluginManagerInterface) doesn't check the context key, only the context data, as the Context API expects us to do.

It serves us well for 2 years, but is is complex.

Proposed resolution

We can rely on the Core's mechanism, checking the data instead of the keys, by:

• never providing 2 or more contexts of the same type for a single source plugin
• forbidding the any context and using entity only when not possible to target a specific entity type (most of the time, to target any fieldable content entity)
• not being shy to create our own contexts with a context class or a typed data plugin if necessary

So, ContextAwarePluginManagerTrait will be able to load only the source plugins whose constraints are satisfied by the provide contexts.

Proposal: We may be able to do everything with only 4 contexts, while keeping it extensible for future usage:

Up-to-date source document: https://docs.google.com/spreadsheets/d/1-oAOLOEYaCaYhMPWKAuwNNTQ5YFeU_44...

We don' t need to create specific context data (so specific Typed Data plugins) with the current proposal, but it may be a good way of reducing the ambiguity of entity, string and integer. However, let's check what contrib space is already proposing before creating our own.

We can start by implementing ContextProviderInterface on the existing "consumer" plugins. This interface is for services, but it seems a good fit also for plugins. It is what we already do in Display Builder.

ComponentBlock

Which is passing the current context (blocks are already context aware):

  public function getRuntimeContexts(array $unqualified_context_ids) {
    return $this->getContexts();
  }

EntityComponentBlock

Same with the (manual? automatic?) addition of entity coming from the display building tool (Layout Builder, at least).

Because entity is already available in ComponentBlock with no value. It may be the opportunity to remove EntityComponentBlock and its deriver.

ComponentFormatter

Currently providing ui_patterns:lang_code (type: any), ui_patterns:field:items (type: any) and field_granularity:items

Proposal:

public function getRuntimeContexts(array $unqualified_context_ids) {
  $entity = $this->sampleEntityGenerator->get($this->fieldDefinition->getTargetEntityTypeId(), $this->fieldDefinition->getTargetBundle());
  return [
    'entity' => EntityContext::fromEntity($entity),
    'field_name' => new Context(new ContextDefinition('string'), $this->fieldDefinition->getName()),
  ];
}

ComponentPerItemFormatter

Currently providing ui_patterns:lang_code (type: any), ui_patterns:field:items (type: any) and ui_patterns:field:index (type: integer)

Proposal (same as ComponentFormatter with the addition of an integer):

public function getRuntimeContexts(array $unqualified_context_ids) {
  $entity = $this->sampleEntityGenerator->get($this->fieldDefinition->getTargetEntityTypeId(), $this->fieldDefinition->getTargetBundle());
  return [
    'entity' => EntityContext::fromEntity($entity),
    'field_name' => new Context(new ContextDefinition('string'), $this->fieldDefinition->getName()),
    'delta' => new Context(new ContextDefinition('integer'), 0),
  ];
}

Then, delta can be dynamically updated

public function viewElements(FieldItemListInterface $items, $langcode) {
  $build = [];
  $contexts = $this->getAvailableContexts();
  foreach ($items as $delta => $item) {
    $contexts['delta'] = new Context(new ContextDefinition('integer'), $delta);
    $build[] = $this->buildComponentRenderable($this->getComponentConfiguration()['component_id'], $contexts);
  }
  return $build;
}

ComponentLayout

Currently providing ui_patterns:form_state (type: any), entity (type: entity).

Proposal: Nothing?

ComponentStyle

Currently providing ui_patterns_views:rows (type: any). And ui_patterns_views:view (type: any), ui_patterns_views:plugin:options (type: any), ui_patterns_views:plugin:display_handler (type: any), ui_patterns_views:view_entity (type: entity:view) through ViewsPluginUiPatternsTrait.

Proposal:

public function getRuntimeContexts(array $unqualified_context_ids) {
  return [
    'view' => EntityContext::fromEntity($this->view->storage),
    'display' => new Context(new ContextDefinition('string'), $this->view->current_display),
  ];
}

ComponentRow

Currently providing ui_patterns_views:row:index (type: integer), entity (type: entity). And ui_patterns_views:view (type: any), ui_patterns_views:plugin:options (type: any), ui_patterns_views:plugin:display_handler (type: any), ui_patterns_views:view_entity (type: entity:view) through ViewsPluginUiPatternsTrait.

Proposal (same as ComponentStyle with the addition of an integer):

public function getRuntimeContexts(array $unqualified_context_ids) {
  return [
    'view' => EntityContext::fromEntity($this->view->storage),
    'display' => new Context(new ContextDefinition('string'), $this->view->current_display),
    'position' => new Context(new ContextDefinition('integer'), $this->position ?? 0),
  ];
}

Context switchers

There are the source plugins actually extending DerivableContextSourceBase:

• EntityFieldSource (entity_field) ([Entity] ➜ [Field]), without a deriver class?
• EntityReferencedSource (entity_reference) ([Entity] ➜ Referenced [Entity])
• EntityReferenceFieldPropertySource (entity:field_property) ([Field item] ➜ Referenced [Entity])

and its EntityReferenceFieldPropertyDerivableContextDeriver

They can be managed as source plugins implementing both:

• ContextAwarePluginInterface like the other context aware source plugins
• ContextProviderInterface like the configurable renderable plugins

For example, EntityFieldSource is aware of:

  context_definitions: [
    'entity' => new ContextDefinition('entity')
  ],

and is providing:

  public function getRuntimeContexts(array $unqualified_context_ids) {
    return [
      'entity' => $this->getContextValue('entity'),
      'field_name' => new Context(new ContextDefinition('string'), $this->getSetting('derivable_context')),
    ];
  }

Ecosystem

What about the other modules (DS, Field Group...)? Are we breaking them? Anyway, it will be a change for the next major version.