OEmbed

OEmbed is a plugin for DokuWiki which supports the OEmbed format for retrieving media embed information. It allows you paste a simple link to the media you want to embed and have the backend automagically embed the data. This alleviates the tedious task of having to copy and paste special embed code which is likely to change and having to support multiple providers if direct input of HTML is not possible.

• Simple syntax
• Supports both JSON and XML responses
• Supports all OEmbed types
• Link discovery
• Local provider list
• Automatic query encoding
• Thumbnail display

To use, simply place the URL of the media in the plugin's tags:

{{>http://www.example.com/path/to/media}}

The plugin supports three methods of resolving the media path to embeddable data. The first is through a direct link in which the API endpoint and media URL are explicitly specified. The second is through link discovery in which an HTTP GET request is made to the media path and the embed data is extracted from the page ala RSS feeds. And the third is through a local list of providers.

A list of content providers that currently support OEmbed can be found on the official OEmbed Website.

The plugin accepts whitespace delimited parameters after the URL. Each parameter must be preceded by either ? for parameters which are passed to the provider or ! for parameters for the plugin. Parameters that are passed to the provider will be automatically URL encoded.

Parameter example:

{{>http://example.com/path/to/media ?maxwidth=200 !thumbnail}}

The following is a list of currently supported plugin parameters:

direct can be used in special cases to bypass any resolution method by explicitly providing the API endpoint and URL. direct can be used as follows:

{{http://example.com/api/oembed !direct ?url=http://example.com/path/to/media}}

thumbnail is used to render a thumbnail of the content with a link to the source instead of fully embedding the media. If the provider does not provide a thumbnail then the plugin will generate a plain link instead.

The OEmbed specification specifies four provider parameters that can be used (url, maxwidth, maxheight, and format). See the official OEmbed website for more information. Providers may specify their own parameters.

The plugin can be configured using DokuWiki's configuration manager. The first setting is the resolution priority. Select which resolution method, link discovery or provider list, is attempted first. If the !direct parameter is in effect it is the only method attempted.

You can enable or disable all three methods by using the next three options. By default direct links and link discovery are enabled but the local provider list is disabled. To use the local provider list edit sample-providers.xml in the plugin directory and rename it providers.xml. Make sure you trust the providers in the list, removing any that you do not. The provider list is a simple XML document with the following structure:

<providers>
    <provider name="Example" api="http://example.com/api/oembed.{format}">
        <scheme>http://example\.com/media/.*?</scheme>
    </provider>
</providers>

You can list as many providers as you like. Each provider element has two attributes: name, which is currently not used, and api which is the URL of the provider's OEmbed API endpoint. If the string {format} is found then it is replaced with either xml or json based on the configuration settings.

Each provider element has scheme elements as children which specify a regular expression which matches against those URLs with which the API endpoint can be used. This regular expression is matched case insensitively and against the entire URL (no need for ^ or $). Since the schemes as listed on http://oembed.com/ are not regular expressions they will need to be converted to be used. Currently, all known OEmbed providers are listed including oohEmbed which acts as a proxy provider, enabling OEmbed to be used with sites that do not have their own native implementation (such as YouTube).

Finally, you can select which response type should be used when given the choice. This normally does not matter. Note, however, that this does not force the use of a response type.

Live examples can be found here.

• v0.6.0 [2008-07-31]
  • FEATURE: Arbitrary parameters can be passed to provider
  • CHANGE: Complete rewrite for maintainability
  • CHANGE: chrome parameter temporarily not supported
  • CHANGE: Horizontal alignment temporarily not supported
  • CHANGE: New parameter passing syntax

Old Versions

• No padding/margin around content.

The plugin supports any compliant OEmbed provider but some providers do not meet the spec exactly. Listed below are the current OEmbed providers and their level of compliance/support.

• Supported: Does the plugin correctly retrieve embed data from this provider?
• Discovery: Does this provider provide autodiscovery of OEmbed data?
• Valid XHTML: If this provider provides HTML embed data is it valid XHTML? (If not it is likely because of use of an embed tag).
• Compliance: Does this provider comply with the official OEmbed specification?
• Documentation: Any official publication of information in regards to the providers OEmbed implementation.

1. XML response does not use text/xml content-type as per spec (2.3.2). Although text/xml is being deprecated in favor of application/xml.
2. XML response does not escape html data as per spec (2.3.2).

Some providers do not provide the content providers but act as proxies to other providers that may or may not support a native OEmbed implementation. One such provider is oohEmbed. In the provided sample-providers.xml oohEmbed is already listed by default.

Discussion and feedback for this plugin can be found in this thread on the DokuWiki forums. You can also contact the author at dbb.0@liqd.org.

• Metadata Display
• Horizontal Alignment
• Caching
• XHTML filter
• ACL integration
• Localization

• Official OEmbed Site
• OEmbed Draft Specification
• OEmbed Group
• OEmbed Wikipedia Article