phpBB Media Embed PlugIn

Frequently Asked Questions

How To Add Sites

What's the deal?
With version 1.1.0 of phpBB Media Embed PlugIn, it is possible to add new sites, in addition to the one's that already come in the default installation. This is handled by physically adding new site definitions in the form of YAML files to the following extension directory ext/phpbb/mediaembed/collection/sites/

New sites will be handled similarly to language packs: Use this support forum topic to submit YAML files for new sites. Users may choose to download and drop them into their extension as desired, and we will try to add these submissions to future releases of this extension.

How to create a YAML file for a new site?
First, you must familiarize yourself with the s9e/MediaEmbed API documentation on how to add new sites here:
Add a custom site - s9e\TextFormatter

You must determine if the site you want to add uses an iframe or flash-based embed code, and if the needed identifiers for the embed code can be found in the site's plain URL. The simplest cases are like the YouTube example. However, some sites can make it very difficult to find their embed codes and may not have useable plain URLs, in which case content scraping will be needed.

Note that familiarity with RegEx patterns is required in order to match and extract the needed video codes from the URL and insert them into the site's embed code. Here are some useful tools for working with RegEx patterns:
Online regex tester and debugger
RegExr

Once you have figured out a RegEx pattern to extract the URL, and have the site's embed code, you should be ready to build the YAML file. While the examples in the s9e/MediaEmbed API Documentation are written in PHP, the basic formatting and structure is essentially the same.

Let's look at their first YouTube example:

Code: Select all

'youtube',
[
	'host'    => 'youtube.com',
	'extract' => "!youtube\\.com/watch\\?v=(?'id'[-0-9A-Z_a-z]+)!",
	'iframe'  => [
		'width'  => 560,
		'height' => 315,
		'src'    => 'http://www.youtube.com/embed/{@id}'
	]
]
Converted to YAML it would look like this:

Code: Select all

name: YouTube
host: youtube.com
example: https://youtube.com/watch?v=123456789
extract: "!youtube\\.com/watch\\?v=(?'id'[-0-9A-Z_a-z]+)!"
iframe:
    width: 560
    height: 315
    src: http://www.youtube.com/embed/{@id}
Let's break it down:
  • Make the YAML file name in lowercase, as it would appear as if it were a BBCode tag: youtube.yml
  • name: This is the displayed name of the site (displayed in our ACP page, for example)
  • host: This is the primary domain of the site hosting the content
  • example: This is optional but helpful where an extension may use the example site URL
  • extract: This is the RegEx pattern that matches the video URL to YouTube, and extracts the 'id' of the video from the URL
  • iframe: YouTube uses an iframe for their embed codes, so this tells MediaEmbed to use an iframe.
    • src: This is YouTube's embed src URL that they use in their iframe. Notice that the extracted id is placed in its proper position using {@id}
    • The width and height are optional.
Here are some useful tools for working with YAML files:
YAML Validator
The YAML Format
Complete idiot's intro to yaml

Also, here is the link to our Pull Request where we added several new site definitions, which may help you undersatnd how these YAML files are done.

How do I use my new site
Drop the YAML file into ext/phpbb/mediaembed/collection/sites/.
It will immediately show up in ACP > Posting > Media Embed > Manage sites.
From there you can enable it.

If the YAML is improperly formatted, you will get a fatal error in phpBB's forums, reporting the problems with the YAML file. Once addressed, phpBB forums should no longer error.

If the site definition is correct, then it will work as soon as you try it... yay! However, if it doesn't work, you'll see something like this in your post: [media]http://www.somesite/foo/bar[/media]
If this happens, the problem could be your RegEx pattern isn't matching correctly, or your iframe or flash embed URLs may be wrong. If you were using content scraping, be aware that content scraping may not always work even if your site definition is good.