Hooks and events¶

The conversion can be changed by other modules in two ways: Symfony events and hooks. Both exist before and after the conversion.

Order¶

For the pre convert step, the event is dispatched first. Then the hook runs on the options that came out of the event. The options that are used are read once, after both.

If a hook and an event set the same option, the hook wins, because it runs last.

Since 2.1.0

In 2.0.x the options that hook_doc_to_html_pre_convert() changed were ignored. See Versions.

The post convert step runs the event first and the hook second, but the two do not chain. The hook receives the HTML as it was before the event. If a subscriber changed the HTML with setFinalHtml(), its result is used and a change from the hook is dropped. If no subscriber changed it, the hook's change is used.

Pre convert¶

Use it to change the options or to cancel the conversion.

Options:

Key	Meaning
`apply_body_regex`	Whether the body regex is applied.
`body_regex`	The body extraction regex.
`body_match_index`	The capture group to return.
`dom_regex`	The DOM regex.
`skip_source_cleanup`	The widget keeps the source file.
`image_directory`	URI of the directory for the images, tokens allowed.
`remove_first_heading`	Whether the first heading is removed.

Hook¶

function example_doc_to_html_pre_convert(array &$options, int $fid, string $uri): void {
  $options['dom_regex'] = '/<style[^>]*>.*?<\/style>/si';
}

Event¶

use Drupal\doc_to_html\Event\DocToHtmlEvents;
use Drupal\doc_to_html\Event\PreConvertEvent;

public static function getSubscribedEvents(): array {
  return [DocToHtmlEvents::PRE_CONVERT => 'onPreConvert'];
}

public function onPreConvert(PreConvertEvent $event): void {
  $options = $event->getOptions();
  $options['dom_regex'] = '/<style[^>]*>.*?<\/style>/si';
  $event->setOptions($options);
}

To cancel the conversion, call $event->cancel('Reason shown to the user.'). A cancelled conversion fails with that message.

PreConvertEvent has getFid(), getUri(), getOptions(), setOptions(), cancel(), isCancelled() and getCancelReason().

Post convert¶

Use it to change the final HTML.

Hook¶

use Drupal\doc_to_html\Services\ConversionResult;

function example_doc_to_html_post_convert(ConversionResult $result, string &$final_html): void {
  $final_html = preg_replace('/ style="[^"]*"/', '', $final_html) ?? $final_html;
}

Event¶

use Drupal\doc_to_html\Event\PostConvertEvent;

public static function getSubscribedEvents(): array {
  return [DocToHtmlEvents::POST_CONVERT => 'onPostConvert'];
}

public function onPostConvert(PostConvertEvent $event): void {
  $event->setFinalHtml(strip_tags($event->getFinalHtml(), '<p><ul><ol><li><h2><h3>'));
}

PostConvertEvent has getResult(), getFinalHtml(), setFinalHtml() and isHtmlModified().

Where it sits in the chain¶

The sanitizing step runs before these hooks and events. HTML that you add in a post convert handler is not sanitized by the module. Keep your own output safe, and rely on the text format filters at render time.