aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Annotation/ContextDefinition.php

   1 <?php
   2
   3 namespace Drupal\Core\Annotation;
   4
   5 use Drupal\Component\Annotation\Plugin;
   6 use Drupal\Core\StringTranslation\TranslatableMarkup;
   7
   8 /**
   9  * @defgroup plugin_context Annotation for context definition
  10  * @{
  11  * Describes how to use ContextDefinition annotation.
  12  *
  13  * When providing plugin annotations, contexts can be defined to support UI
  14  * interactions through providing limits, and mapping contexts to appropriate
  15  * plugins. Context definitions can be provided as such:
  16  * @code
  17  *   context = {
  18  *     "node" = @ContextDefinition("entity:node")
  19  *   }
  20  * @endcode
  21  *
  22  * To add a label to a context definition use the "label" key:
  23  * @code
  24  *   context = {
  25  *     "node" = @ContextDefinition("entity:node", label = @Translation("Node"))
  26  *   }
  27  * @endcode
  28  *
  29  * Contexts are required unless otherwise specified. To make an optional
  30  * context use the "required" key:
  31  * @code
  32  *   context = {
  33  *     "node" = @ContextDefinition("entity:node", required = FALSE, label = @Translation("Node"))
  34  *   }
  35  * @endcode
  36  *
  37  * To define multiple contexts, simply provide different key names in the
  38  * context array:
  39  * @code
  40  *   context = {
  41  *     "artist" = @ContextDefinition("entity:node", label = @Translation("Artist")),
  42  *     "album" = @ContextDefinition("entity:node", label = @Translation("Album"))
  43  *   }
  44  * @endcode
  45  *
  46  * Specifying a default value for the context definition:
  47  * @code
  48  *   context = {
  49  *     "message" = @ContextDefinition("string",
  50  *       label = @Translation("Message"),
  51  *       default_value = @Translation("Checkout complete! Thank you for your purchase.")
  52  *     )
  53  *   }
  54  * @endcode
  55  *
  56  * @see annotation
  57  *
  58  * @}
  59  */
  60
  61 /**
  62  * Defines a context definition annotation object.
  63  *
  64  * Some plugins require various data contexts in order to function. This class
  65  * supports that need by allowing the contexts to be easily defined within an
  66  * annotation and return a ContextDefinitionInterface implementing class.
  67  *
  68  * @Annotation
  69  *
  70  * @ingroup plugin_context
  71  */
  72 class ContextDefinition extends Plugin {
  73
  74   /**
  75    * The ContextDefinitionInterface object.
  76    *
  77    * @var \Drupal\Core\Plugin\Context\ContextDefinitionInterface
  78    */
  79   protected $definition;
  80
  81   /**
  82    * Constructs a new context definition object.
  83    *
  84    * @param array $values
  85    *   An associative array with the following keys:
  86    *   - value: The required data type.
  87    *   - label: (optional) The UI label of this context definition.
  88    *   - required: (optional) Whether the context definition is required.
  89    *   - multiple: (optional) Whether the context definition is multivalue.
  90    *   - description: (optional) The UI description of this context definition.
  91    *   - default_value: (optional) The default value in case the underlying
  92    *     value is not set.
  93    *   - class: (optional) A custom ContextDefinitionInterface class.
  94    *
  95    * @throws \Exception
  96    *   Thrown when the class key is specified with a non
  97    *   ContextDefinitionInterface implementing class.
  98    */
  99   public function __construct(array $values) {
 100     $values += [
 101       'required' => TRUE,
 102       'multiple' => FALSE,
 103       'default_value' => NULL,
 104     ];
 105     // Annotation classes extract data from passed annotation classes directly
 106     // used in the classes they pass to.
 107     foreach (['label', 'description'] as $key) {
 108       // @todo Remove this workaround in https://www.drupal.org/node/2362727.
 109       if (isset($values[$key]) && $values[$key] instanceof TranslatableMarkup) {
 110         $values[$key] = (string) $values[$key]->get();
 111       }
 112       else {
 113         $values[$key] = NULL;
 114       }
 115     }
 116     if (isset($values['class']) && !in_array('Drupal\Core\Plugin\Context\ContextDefinitionInterface', class_implements($values['class']))) {
 117       throw new \Exception('ContextDefinition class must implement \Drupal\Core\Plugin\Context\ContextDefinitionInterface.');
 118     }
 119     $class = isset($values['class']) ? $values['class'] : 'Drupal\Core\Plugin\Context\ContextDefinition';
 120     $this->definition = new $class($values['value'], $values['label'], $values['required'], $values['multiple'], $values['description'], $values['default_value']);
 121   }
 122
 123   /**
 124    * Returns the value of an annotation.
 125    *
 126    * @return \Drupal\Core\Plugin\Context\ContextDefinitionInterface
 127    */
 128   public function get() {
 129     return $this->definition;
 130   }
 131
 132 }