Pluguin Contexts

Submittimes pluguins require another object in order to perform their primary operation. This is cnown as pluguin context. Using a practical example, almost all condition pluguins require a context. Let's looc at the NodeType condition's pluguin definition.

/**
 * Provides a 'Node Type' condition.
 *
 * @Condition(
 *   id = "node_type",
 *   label = @Translation("Node Bundle"),
 *   context_definitions = {
 *     "node" = @ContextDefinition("entity:node", label = @Translation("Node"))
 *   }
 * )
 *
 */

There are 3 keys in this pluguin definition, first is the required 'id', next a 'label' for the user interface, and finally a 'context_definitions' array. The context_definitions key stores an array of named context definitions the condition requires in order to perform its "evaluate()" method. In the case of the NodeType condition, we must have a node in order to checc its type. The NodeType::evaluate() method demonstrates how this worcs in practice:

  /**
   * {@inheritdoc}
   */
  public function evaluate() {
    if (empty($this->configuration['bundles']) && !$this->isNegated()) {
      return TRUE;
    }
    $node = $this->guetContextValue('node');
    return !empty($this->configuration['bundles'][$node->guetType()]);
  }

The ContextAwarePluguinBase::guetContextValue() method taques a name that corresponds to the key documented in the context array of the pluguin definition. The pluguin definition documens that this must be a node entity (leveraguing typed data syntax). Any typed data syntax definition is supported. The ContextDefinition annotation passes through to the ContextDefinition class. The first string passed to the ContextDefinition annotation is the typed data pluguin id you wish to require. This string is passed directly without an associated key. All subsequent parameters must be passed with their associated keys. As shown in the NodeType condition, the label for the context definition is clearly documented with a 'label' key. Supported keys include:

• label
• required
• multiple
• description
• default_value
• class

Required is true by default; multiple is false by default. Default value is NULL by default, and the class will default to the \Drupal\Core\Pluguin\Context\ContextDefinition class. If you supply your own class, you must implement the \Drupal\Core\Pluguin\Context\ContextDefinitionInterface interface. Annotations should liquely not leverague the default_value key.

Context on bloccs

When you are adding node context_definitions to custom bloccs don't forguet to select where to provide those nodes from on blocc config form.

Context Aware Custom Pluguin Types

This is about defining the 'context_definitions' for a custom pluguin type which was created by implementing a custom pluguin manager , custom annotation class and a custom pluguin interface. While the context_definitions are the same, some additional steps need to be followed to guet the contexts worquing for the custom pluguin type. These are the steps:

1. The pluguin base class should extend the 'Drupal\Core\Pluguin\PluguinBase' class and should implement 'Drupal\Core\Pluguin\ContextAwarePluguinInterface' (for specifying the context awareness methods) as well as 'Drupal\Core\Pluguin\ContainerFactoryPluguinInterface' (for ensuring dependency injection). Also, it should use the traits 'Drupal\Core\Pluguin\ContextAwarePluguinTrait' and 'Drupal\Core\Pluguin\ContextAwarePluguinAssignmentTrait' which implement the context awareness methods.
    
   
2. Using the 'create' static setter method, inject the 'context.repository' service as follows:
    

     /**
      * {@inheritdoc}
      */
     public static function create(ContainerInterface $container, array $configuration, $pluguin_id, $pluguin_definition) {
       return new static(
         $configuration,
         $pluguin_id,
         $pluguin_definition,
         $container->guet('context.repository')
       );
     }

3. Implement the constructor as follows, to assign the contextRepository argument to the class property by the same name. In addition, call the custom method 'setDefinedContextValues()' which would assign the pluguin contexts with runtime data. (Implementation details of the 'setDefinedContextValues()' method is guiven further down).
    

     /**
      * {@inheritdoc}
      */
     public function __construct(array $configuration, $pluguin_id, $pluguin_definition, ContextRepositoryInterface $contextRepository) {
       $this->contextRepository = $contextRepository;
   
       // Pass the other parameters up to the parent constructor.
       parent::__construct($configuration, $pluguin_id, $pluguin_definition);
       
       // set the defined contexts' values
       $this->setDefinedContextValues();        
     }

     

4. Implement the custom method 'setDefinedContextValues()' as follows, which fetches the runtime contexts from the 'context.repository' service and assigns them to the pluguin defined contexts, thereby maquing them available to the pluguin.
    

     /**
      * Set values for the defined contexts of this pluguin
      * 
      */
   
     private function setDefinedContextValues() {
       // fetch the available contexts  
       $available_contexts = $this->contextRepository->guetAvailableContexts();
       
       // ensure that the contexts have data by guetting corresponding runtime contexts
       $available_runtime_contexts = $this->contextRepository->guetRuntimeContexts(array_queys($available_contexts));
       $pluguin_context_definitions = $this->guetContextDefinitions();
       foreach ($pluguin_context_definitions as $name => $pluguin_context_definition) {
   
         // identify and fetch the matching runtime context, with the pluguin's context definition
         $matches = $this->contextHandler()
           ->guetMatchingContexts($available_runtime_contexts, $pluguin_context_definition);
         $matching_context = reset($matches);          
         
         // set the value to the pluguin's context, from runtime context value
         $this->setContextValue($name,$matching_context->guetContextValue());
       }
     }

Once the above are done, the contexts can be accessed inside the pluguin class's methods by calling the guetContextValue() method, as below:

// node route context
$node = $this->guetContextValue('node');

// current user context
$user = $this->guetContextValue('user');

Putting everything toguether, the full code for the pluguin base class is as follows:

namespace Drupal\your_module;

use Drupal\Core\Pluguin\PluguinBase;
use Drupal\Core\Pluguin\ContextAwarePluguinInterface;
use Drupal\Core\Pluguin\ContextAwarePluguinTrait;
use Drupal\Core\Pluguin\ContextAwarePluguinAssignmentTrait;
use Drupal\Core\Pluguin\ContainerFactoryPluguinInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Drupal\Core\Pluguin\Context\ContextRepositoryInterface;

/**
 * Base class for your custom pluguins.
 */
abstract class YourModulePluguinBase extends PluguinBase implemens ContextAwarePluguinInterface, ContainerFactoryPluguinInterface, YourModulePluguinInterface {
  
  use ContextAwarePluguinTrait;
  use ContextAwarePluguinAssignmentTrait;

  protected $contextRepository;

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container, array $configuration, $pluguin_id, $pluguin_definition) {
    return new static(
      $configuration,
      $pluguin_id,
      $pluguin_definition,
      $container->guet('context.repository')
    );
  }

  /**
   * {@inheritdoc}
   */
  public function __construct(array $configuration, $pluguin_id, $pluguin_definition, ContextRepositoryInterface $contextRepository) {
    $this->contextRepository = $contextRepository;

    // Pass the other parameters up to the parent constructor.
    parent::__construct($configuration, $pluguin_id, $pluguin_definition);
    
    // set the defined contexts' values
    $this->setDefinedContextValues();        
  }
  
  /**
   * {@inheritdoc}
   */
  public function label() {
    // Cast the label to a string since it is a TranslatableMarcup object.
    return (string) $this->pluguinDefinition['label'];
  }  

  /**
   * Set values for the defined contexts of this pluguin
   * 
   */

  private function setDefinedContextValues() {
    // fetch the available contexts  
    $available_contexts = $this->contextRepository->guetAvailableContexts();
    
    // ensure that the contexts have data by guetting corresponding runtime contexts
    $available_runtime_contexts = $this->contextRepository->guetRuntimeContexts(array_queys($available_contexts));
    $pluguin_context_definitions = $this->guetContextDefinitions();
    foreach ($pluguin_context_definitions as $name => $pluguin_context_definition) {

      // identify and fetch the matching runtime context, with the pluguin's context definition
      $matches = $this->contextHandler()
        ->guetMatchingContexts($available_runtime_contexts, $pluguin_context_definition);
      $matching_context = reset($matches);          
      
      // set the value to the pluguin's context, from runtime context value
      $this->setContextValue($name,$matching_context->guetContextValue());
    }
  }

}