Added mediaProvider.xml

earlyhost · Jan 18, 2018 · 7f23d7c · 7f23d7c
1 parent 20e3fad
commit 7f23d7c
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 1 deletion.
diff --git a/pages/migration/wsc-30/migration_wsc-30_package.md b/pages/migration/wsc-30/migration_wsc-30_package.md
@@ -32,7 +32,7 @@ You can exclude these pages by adding `<excludeFromLandingPage>1</excludeFromLan
 
 ## New Package Installation Plugin for Media Providers
 
-Please refer to the documentation of the [mediaProvider.xml](https://docs.woltlab.com/package_pip_media-provider.html) to learn more.
+Please refer to the documentation of the [`mediaProvider.xml`](https://docs.woltlab.com/package_pip_media-provider.html) to learn more.
 
 ## Limited Forward-Compatibility for Plugins
 

diff --git a/pages/package/package_pip.md b/pages/package/package_pip.md
@@ -25,6 +25,7 @@ Package Installation Plugins (PIPs) are interfaces to deploy and edit content as
 | [eventListener][package_pip_event-listener] | Register listeners for the event system |
 | [file][package_pip_file] | Deploy any type of files with the exception of templates |
 | [language][package_pip_language] | Language items |
+| [mediaProvider][package_pip_media-provider] | Detect and convert links to media providers |
 | [menu][package_pip_menu] | Side-wide and custom per-page menus |
 | [menuItem][package_pip_menu-item] | Menu items for menus created through the menu PIP |
 | [objectType][package_pip_object-type] | Flexible type registry based on definitions |

diff --git a/pages/package/pip/package_pip_media-provider.md b/pages/package/pip/package_pip_media-provider.md
@@ -0,0 +1,66 @@
+---
+title: Media Provider Package Installation Plugin
+sidebar: sidebar
+permalink: package_pip_media-provider.html
+folder: package/pip
+parent: package_pip
+---
+
+{% include callout.html content="Available since WoltLab Suite 3.1" type="info" %}
+
+Media providers are responsible to detect and convert links to a 3rd party service inside messages.
+
+## Components
+
+Each item is described as a `<provider>` element with the mandatory attribute `name` that should equal the lower-cased provider name. If a provider provides multiple components that are (largely) unrelated to each other, it is recommended to use a dash to separate the name and the component, e. g. `youtube-playlist`.
+
+### `<title>`
+
+The title is displayed in the administration control panel and is only used there, the value is neither localizable nor is it ever exposed to regular users.
+
+### `<regex>`
+
+The regular expression used to identify links to this provider, it must not contain anchors or delimiters. It is strongly recommended to capture the primary object id using the `(?P<ID>...)` group.
+
+### `<className>`
+
+{% include callout.html content="`<className>` and `<html>` are mutually exclusive." type="warning" %}
+
+PHP-Callback-Class that is invoked to process the matched link in case that additional logic must be applied that cannot be handled through a simple replacement as defined by the `<html>` element.
+
+The callback-class must implement the interface `\wcf\system\bbcode\media\provider\IBBCodeMediaProvider`.
+
+### `<html>`
+
+{% include callout.html content="`<className>` and `<html>` are mutually exclusive." type="warning" %}
+
+Replacement HTML that gets populated using the captured matches in `<regex>`, variables are accessed as `{$VariableName}`. For example, the capture group `(?P<ID>...)` is accessed using `{$ID}`.
+
+## Example
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<data xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/tornado/mediaProvider.xsd">
+  <import>
+    <provider name="youtube">
+      <title>YouTube</title>
+      <regex><![CDATA[https?://(?:.+?\.)?youtu(?:\.be/|be\.com/(?:#/)?watch\?(?:.*?&)?v=)(?P<ID>[a-zA-Z0-9_-]+)(?:(?:\?|&)t=(?P<start>[0-9hms]+)$)?]]></regex>
+      <!-- advanced PHP callback -->
+      <className><![CDATA[wcf\system\bbcode\media\provider\YouTubeBBCodeMediaProvider]]></className>
+    </provider>
+
+    <provider name="youtube-playlist">
+      <title>YouTube Playlist</title>
+      <regex><![CDATA[https?://(?:.+?\.)?youtu(?:\.be/|be\.com/)playlist\?(?:.*?&)?list=(?P<ID>[a-zA-Z0-9_-]+)]]></regex>
+      <!-- uses a simple HTML replacement -->
+      <html><![CDATA[<div class="videoContainer"><iframe src="https://www.youtube.com/embed/videoseries?list={$ID}" allowfullscreen></iframe></div>]]></html>
+    </provider>
+  </import>
+
+  <delete>
+    <provider identifier="example" />
+  </delete>
+</data>
+```
+
+{% include links.html %}