3 namespace Drupal\filter\Plugin\Filter;
5 use Drupal\Component\Utility\Html;
6 use Drupal\Component\Utility\Xss;
7 use Drupal\filter\FilterProcessResult;
8 use Drupal\filter\Plugin\FilterBase;
9 use Drupal\filter\Render\FilteredMarkup;
12 * Provides a filter to caption elements.
14 * When used in combination with the filter_align filter, this must run last.
17 * id = "filter_caption",
18 * title = @Translation("Caption images"),
19 * description = @Translation("Uses a <code>data-caption</code> attribute on <code><img></code> tags to caption images."),
20 * type = Drupal\filter\Plugin\FilterInterface::TYPE_TRANSFORM_REVERSIBLE
23 class FilterCaption extends FilterBase {
28 public function process($text, $langcode) {
29 $result = new FilterProcessResult($text);
31 if (stristr($text, 'data-caption') !== FALSE) {
32 $dom = Html::load($text);
33 $xpath = new \DOMXPath($dom);
34 foreach ($xpath->query('//*[@data-caption]') as $node) {
35 // Read the data-caption attribute's value, then delete it.
36 $caption = Html::escape($node->getAttribute('data-caption'));
37 $node->removeAttribute('data-caption');
39 // Sanitize caption: decode HTML encoding, limit allowed HTML tags; only
40 // allow inline tags that are allowed by default, plus <br>.
41 $caption = Html::decodeEntities($caption);
42 $caption = FilteredMarkup::create(Xss::filter($caption, ['a', 'em', 'strong', 'cite', 'code', 'br']));
44 // The caption must be non-empty.
45 if (mb_strlen($caption) === 0) {
49 // Given the updated node and caption: re-render it with a caption, but
50 // bubble up the value of the class attribute of the captioned element,
51 // this allows it to collaborate with e.g. the filter_align filter.
52 $tag = $node->tagName;
53 $classes = $node->getAttribute('class');
54 $node->removeAttribute('class');
55 $node = ($node->parentNode->tagName === 'a') ? $node->parentNode : $node;
57 '#theme' => 'filter_caption',
58 // We pass the unsanitized string because this is a text format
59 // filter, and after filtering, we always assume the output is safe.
60 // @see \Drupal\filter\Element\ProcessedText::preRenderText()
61 '#node' => FilteredMarkup::create($node->C14N()),
63 '#caption' => $caption,
64 '#classes' => $classes,
66 $altered_html = \Drupal::service('renderer')->render($filter_caption);
68 // Load the altered HTML into a new DOMDocument and retrieve the element.
69 $updated_nodes = Html::load($altered_html)->getElementsByTagName('body')
73 foreach ($updated_nodes as $updated_node) {
74 // Import the updated node from the new DOMDocument into the original
75 // one, importing also the child nodes of the updated node.
76 $updated_node = $dom->importNode($updated_node, TRUE);
77 $node->parentNode->insertBefore($updated_node, $node);
79 // Finally, remove the original data-caption node.
80 $node->parentNode->removeChild($node);
83 $result->setProcessedText(Html::serialize($dom))
97 public function tips($long = FALSE) {
100 <p>You can caption images, videos, blockquotes, and so on. Examples:</p>
102 <li><code><img src="" data-caption="This is a caption" /></code></li>
103 <li><code><video src="" data-caption="The Drupal Dance" /></code></li>
104 <li><code><blockquote data-caption="Dries Buytaert">Drupal is awesome!</blockquote></code></li>
105 <li><code><code data-caption="Hello world in JavaScript.">alert("Hello world!");</code></code></li>
109 return $this->t('You can caption images (<code>data-caption="Text"</code>), but also videos, blockquotes, and so on.');