TextformatterVideoMarkup by NB Communication

Render oEmbed data from YouTube/Vimeo URLs.

Textformatter Video Markup

Render oEmbed data from YouTube/Vimeo URLs. Based on TextformatterVideoEmbed by Ryan Cramer and TextformatterVideoEmbedOptions by Steffen Henschel.


  • ProcessWire >= 3.0.148
  • PHP >= 7


  1. Download the zip file at Github or clone the repo into your site/modules directory.
  2. If you downloaded the zip file, extract it in your sites/modules directory.
  3. In your admin, go to Modules > Refresh, then Modules > New, then click on the Install button for this module.

How to use

  • Edit the field you will be placing videos in. This can be any Text field e.g. Text, Textarea (CKEditor or not), URL etc.
  • On the Details tab, select "Video markup for YouTube/Vimeo" in Text Formatters and Save.
  • Edit a page using the field you've edited and paste in YouTube and/or Vimeo video URLs. If the field is using CKEditor, make sure each URL is on its own paragraph.



This is the template that will be used to render the oEmbed data. It does this through the use of placeholders wrapped in curly brackets. Each endpoint should provide:

  • type: video.
  • version: 1.0.
  • title: A text title, describing the video.
  • author_name: The name of the author/owner of the video.
  • author_url: A URL for the author/owner of the video.
  • provider_name: YouTube or Vimeo.
  • provider_url: https://www.youtube.com/ or https://vimeo.com/.
  • thumbnail_url: A URL to a thumbnail image for the video.
  • thumbnail_width: The width of the thumbnail.
  • thumbnail_height: The height of the thumbnail.
  • html: The HTML embed code.
  • width: The width in pixels required to display the video.
  • height: The height in pixels required to display the video.

Vimeo also returns a number of custom properties. For more information on these please see https://developer.vimeo.com/api/oembed/videos#table-3.

These additional placeholders are also available:

  • video_id: The ID of the video
  • url: The requested URL.
  • embedUrl: The embed URL.
  • class: yt or vm. Useful for styling YouTube/Vimeo markup differently.
  • lite: A pre-rendered facade. See Facades below.


If $config->debug is set to true, you can output a table of the data returned by the oEmbed endpoint using the {debug} placeholder.

Example - Thumbnail image with UIkit Lightbox

<figure data-uk-lightbox>
    <a href="{url}" data-poster="{thumbnail_url}" data-attrs="width: {width}; height: {height}">
        <img src="{thumbnail_url}" alt="{title}">

In debug mode, a table of the oEmbed data is appended.

Video Options

  • Max Width: The video width.
  • Max Height: The video height.
  • Empty Value: The value that will be rendered if no response is received from the oEmbed endpoint.

For the empty value, the following placeholders can be used:

  • {url}: Outputs the requested URL.
  • {link}: Outputs the requested URL as a link.

YouTube/Vimeo Options

These allow global configuration of videos. Not all options are available, just those that could be useful to set globally. For example, YouTube allows start and end parameter options - it wouldn't make sense to set these for every video on your site!

You can override the global defaults in the URL request e.g. https://www.youtube.com/watch?v=ScMzIvxBSi4&controls=0&color=white. The exception to this is YouTube's privacy-enhanced mode, which is not a paramater option, but a different URL.

If multi-language support is enabled, language paramaters will default to the name of the user's language e.g. https://www.youtube.com/watch?v=ScMzIvxBSi4&cc_lang_pref=fr&hl=fr.

More information on these options can be found here: YouTube / Vimeo

Note: YouTube's rel=0 doesn't behave the way it used to - see the link above for more information.


The preferred way of loading 3rd-party resources is via a facade: https://developer.chrome.com/docs/lighthouse/performance/third-party-facades.

This module creates the markup appropriate for https://github.com/paulirish/lite-youtube-embed and https://github.com/luwes/lite-vimeo-embed and it can be accessed via the lite property. You will need to implement the required assets yourself for this to work.


Any data returned by the oEmbed endpoints is cached permanently unless cleared manually, which you can do so here.


The render() method is hookable, allowing you to customise rendering on a per page, per field basis.

// in site/ready.php
$wire->addHookBefore('TextformatterVideoMarkup::render', function(HookEvent $event) {

	// Arguments
	$tpl = $event->arguments(0); // string: The markup template
	$data = $event->arguments(1); // array: The oEmbed data
	$url = $event->arguments(2); // string: The requested URL
	$emptyValue = $event->arguments(3); // string: The empty value used if no data is returned

	// Object properties
	$page = $event->object->page; // Page: The page
	$field = $event->object->field; // Field: The field
	$html = $event->object->html; // bool: Is it HTML being parsed, or plain text?
	// Example 1 - Replace the thumbnail image
	if($field->name == 'video' && $page->hasField('images') && $page->images->count) {
		$data['thumbnail_url'] =  $page->images->first->url;
		$event->arguments(1, $data);

	// Example 2 - Set empty values by fieldtype
	switch((string) $field->type) {
		case 'FieldtypeTextarea':
			$msg = sprintf(__('Sorry, the video (%s) could not be rendered.'), $url);
			$emptyValue = $html ? '<p>' . strip_tags($msg) . '</p>' : $msg;
		case 'FieldtypeURL':
			$event->arguments(0, '{title}'); // Also set the tpl
			$emptyValue = '{link}';
	$event->arguments(3, $emptyValue);


If the data cannot be retrieved, e.g. the video is private, a blank string is returned.

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Latest news

  • ProcessWire Weekly #523
    In the 523rd issue of ProcessWire Weekly we'll check out what's new in the core this week, share some new module related news, and more. Read on!
    Weekly.pw / 18 May 2024
  • ProFields Table Field with Actions support
    This week we have some updates for the ProFields table field (FieldtypeTable). These updates are primarily focused on adding new tools for the editor to facilitate input and management of content in a table field.
    Blog / 12 April 2024
  • Subscribe to weekly ProcessWire news

“We were really happy to build our new portfolio website on ProcessWire! We wanted something that gave us plenty of control on the back-end, without any bloat on the front end - just a nice, easy to access API for all our content that left us free to design and build however we liked.” —Castus, web design agency in Sheffield, UK