====== OEmbed ======
**OEmbed** is a plugin for [[http://www.dokuwiki.org/dokuwiki|DokuWiki]] which supports the [[http://oembed.com/|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.

===== Features =====
  * Simple syntax
  * Supports both [[wp>JSON]] and [[wp>XML]] responses
  * Supports all OEmbed types
  * Link discovery
  * Local provider list
  * Automatic query encoding
  * Thumbnail display

===== Usage =====
<note warning>Since the plugin inserts raw HTML from a remote source, it is vulnerable to a [[wp>cross-site_scripting|cross-site scripting]] (XSS) attack. Only use the plugin with trusted providers.</note>
<note important>The following reflects the plugin's usage and syntax as of the latest version. The plugin's syntax is subject to change until version 1.0. </note>

==== Basic ====
To use, simply place the URL of the media in the plugin's tags:
<code>{{>http://www.example.com/path/to/media}}</code>

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 [[http://oembed.com/|OEmbed Website]].

==== Parameters ====
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:
<code>{{>http://example.com/path/to/media ?maxwidth=200 !thumbnail}}</code>

The following is a list of currently supported plugin parameters:
^  Parameter    ^                      Effect                      ^
| ''direct''    | The URL should be interpreted as an API endpoint |
| ''thumbnail'' | Display a thumbnail of content with link         |

''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:
<code>{{http://example.com/api/oembed !direct ?url=http://example.com/path/to/media}}</code>

''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.

==== Configuration ====
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:

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

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 [[http://oembed.com/|oohEmbed]] which acts as a proxy provider, enabling OEmbed to be used with sites that do not have their own native implementation (such as [[http://www.youtube.com/|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.

==== Examples ====
Live examples can be found [[oembed:example|here]].

===== Download =====
<note tip>
  * The plugin works with DokuWiki's plugin manager using this ''[[http://liqd.org/wiki/_media/oembed/oembed-latest.zip|URL]]''.
  * To manually install, unzip the archive to DokuWiki's ''lib/plugins/'' directory.
  * The latest version is v0.6.0
</note>

{{filelist>:oembed:*&order=desc&style=table&tableshowsize=1&tableheader=1}}

==== Change Log ====
  * **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 |
  * **v0.5.0** [2008-07-29]
    * FEATURE: Link discovery (section 4 of specification)
    * FEATURE: Local provider list
    * FEATURE: Various configuration settings
    * CHANGE: Significant code refactoring
    * CHANGE: Template colors are used to decorate chrome
    * CHANGE: Improved chrome styling
    * CHANGE: Now uses DokuWiki's built-in JSON decoder, no longer dependent upon ''json'' extension
    * FIX: Link type uses query URL instead of target URL

  * **v0.4.0** [2008-06-11]
    * FEATURE: Thumbnail support using ''thumbnail'' parameter
    * CHANGE: Reversed order of provider and source links in ''chrome''
    * CHANGE: Miscellaneous CSS changes

  * **v0.3.1** [2008-06-09]
    * CHANGE: Links in ''chrome'' open in new window
    * CHANGE: Added link to original content when using ''chrome''
    * FIX: CSS layout problems related to right alignment
    * FIX: ''link'' media type uses wrong URL

  * **v0.3.0** [2008-06-09]
    * FEATURE: Horizontal alignment of embedded content
    * FEATURE: Rich display of content metadata by using the ''chrome'' parameter
    * CHANGE: More compliant ''Content-Type'' header handling 
    * CHANGE: OEmbed ''version'' is now checked for compatibility
    * CHANGE: Failures are passed through for debugging

  * **v0.2.0** [2008-06-08]
    * CHANGE: Using DokuWiki's internal HTTP client, eliminating the dependency on the ''pcl_http'' extension

  * **v0.1.0** [2008-06-08]
    * RELEASE
++++

===== Known Issues =====
  * No padding/margin around content.

===== Provider Support =====
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.

^              Provider                ^   Supported   ^  Discovery  ^  Valid XHTML  ^    Compliance   ^  Documentation  ^
^ [[http://vimeo.com/|Vimeo]]          |      Yes      |     Yes     |      Yes      |     **Full**    | [[http://vimeo.com/api/docs/oembed|Vimeo API]] |
^ [[http://www.flickr.com/|Flickr]]    |      Yes      |     No      |      N/A      |     **Full**    | |
^ [[http://www.hulu.com/|Hulu]]        |      Yes      |     No      |      No       |      ''1''      | [[http://blog.hulu.com/2008/5/27/sharing-is-easy|Hulu Blog]] |
^ [[http://qik.com/|Qik]]              |      Yes      |     No      |      No       |      ''1''      | [[http://qik.com/blog/124/qik-embraces-oembed-for-embedding-videos|Qik Blog]] |
^ [[http://www.viddler.com/|Viddler]]  |   Yes (JSON)  |     No      |      No       |      ''2''      | [[http://wiki.developers.viddler.com/index.php/OEMBED|Viddler API]] |
^ [[http://revision3.com/|Revision3]]  |   Yes (JSON)  |     No      |      No       |      ''2''      | |


  - 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''.
  - 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 [[http://oohembed.com/|oohEmbed]]. In the provided ''sample-providers.xml'' oohEmbed is already listed by default.

===== Discussion =====
Discussion and feedback for this plugin can be found in this [[http://forum.dokuwiki.org/thread/2202|thread]] on the DokuWiki forums. You can also contact the author at <dbb.0@liqd.org>.

===== Wish List =====
<note>Not all items on the wish list are guaranteed to be implemented.</note>
  * Metadata Display
  * Horizontal Alignment
  * Caching  
  * XHTML filter
  * ACL integration
  * Localization

===== Useful Links =====
  * [[http://oembed.com/|Official OEmbed Site]]
  * [[http://oembed.com/draft.htm|OEmbed Draft Specification]]
  * [[http://groups.google.com/group/oembed|OEmbed Group]]
  * [[wp>OEmbed|OEmbed Wikipedia Article]]