www.aleph1.co.uk Git - yaffs-website/blob - web/themes/contrib/bootstrap/docs/plugins/Prerender.md

   1 <!-- @file Documentation for the @BootstrapPrerender annotated plugin. -->
   2 <!-- @defgroup -->
   3 <!-- @ingroup -->
   4 # @BootstrapPrerender
   5
   6 - [Create a plugin](#create)
   7 - [Rebuild the cache](#rebuild)
   8
   9 ---
  10
  11 ## Create a plugin {#create}
  12
  13 We'll use `Link` implemented by this base theme as an example of how to add
  14 custom classes and an icon to make the link look like a Bootstrap button. This
  15 example will only work if the link is passed some sort of `#context` when the
  16 render array is built, like the following:
  17
  18 ```php
  19 <?php
  20 $build['my_button'] = [
  21   '#type' => 'link',
  22   '#title' => t('Download'),
  23   '#url' => Url::fromUserInput('/download', [
  24     'query' => ['item' => '1234'],
  25   ]),
  26   '#context' => [
  27     'downloadButton' => TRUE,
  28   ],
  29 ];
  30 ?>
  31 ```
  32
  33 Replace all following instances of `THEMENAME` with the actual machine name of
  34 your sub-theme.
  35
  36 Create a file at `./THEMENAME/src/Plugin/Prerender/Link.php` with the
  37 following contents:
  38
  39 ```php
  40 <?php
  41
  42 namespace Drupal\THEMENAME\Plugin\Prerender;
  43
  44 use Drupal\bootstrap\Plugin\Prerender\Link as BootstrapLink;
  45 use Drupal\bootstrap\Bootstrap;
  46 use Drupal\bootstrap\Utility\Element;
  47
  48 /**
  49  * Pre-render callback for the "link" element type.
  50  *
  51  * @ingroup plugins_prerender
  52  *
  53  * @BootstrapPrerender("link",
  54  *   action = @BootstrapConstant(
  55  *     "\Drupal\bootstrap\Bootstrap::CALLBACK_PREPEND"
  56  *   )
  57  * )
  58  *
  59  * @see \Drupal\Core\Render\Element\Link::preRenderLink()
  60  */
  61 class Link extends BootstrapLink {
  62   /*
  63    * It should be noted that you do not need both methods here.
  64    * This is to just show you the different examples of how this plugin
  65    * works and how it can be tailored to your needs.
  66    */
  67
  68   /**
  69    * {@inheritdoc}
  70    */
  71   public static function preRender(array $element) {
  72     $context = isset($element['#context']) ? $element['#context'] : [];
  73
  74     // Make downloadButton links into buttons.
  75     if (!empty($context['downloadButton'])) {
  76       $element['#icon'] = Bootstrap::glyphicon('download-alt');
  77       $element['#attributes']['class'][] = 'btn';
  78       $element['#attributes']['class'][] = 'btn-primary';
  79       $element['#attributes']['class'][] = 'btn-lg';
  80     }
  81
  82     // You must always return the element in this method, as well as call the
  83     // parent method when sub-classing this method as it is used to invoke
  84     // static::preRenderElement().
  85     return parent::preRender($element);
  86   }
  87
  88   /**
  89    * {@inheritdoc}
  90    */
  91   public static function preRenderElement(Element $element) {
  92     // Make downloadButton links into buttons.
  93     // Same as above, just a little cleaner with the Element utility class.
  94     if ($element->getContext('downloadButton')) {
  95       $element->addClass(['btn', 'btn-primary', 'btn-lg'])->setIcon(Bootstrap::glyphicon('download-alt'));
  96     }
  97
  98     // You don't always have to call the parent method when sub-classing, but
  99     // it is generally recommended that you do (otherwise the icon that was
 100     // just added wouldn't work).
 101     parent::preRenderElement($element);
 102   }
 103
 104 }
 105 ?>
 106 ```
 107
 108 ## Rebuild the cache {#rebuild}
 109
 110 Once you have saved, you must rebuild your cache for this new plugin to be
 111 discovered. This must happen anytime you make a change to the actual file name
 112 or the information inside the `@BootstrapPrerender` annotation.
 113
 114 To rebuild your cache, navigate to `admin/config/development/performance` and
 115 click the `Clear all caches` button. Or if you prefer, run `drush cr` from the
 116 command line.
 117
 118 Voilà! After this, you should have a fully functional `@BootstrapPrerender`
 119 plugin!