docs/package/pip/media-provider.md

   1 # Media Provider Package Installation Plugin
   2
   3 !!! info "Available since WoltLab Suite 3.1"
   4
   5 Media providers are responsible to detect and convert links to a 3rd party service inside messages.
   6
   7 ## Components
   8
   9 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`.
  10
  11 ### `<title>`
  12
  13 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.
  14
  15 ### `<regex>`
  16
  17 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.
  18
  19 ### `<className>`
  20
  21 !!! warning "`<className>` and `<html>` are mutually exclusive."
  22
  23 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.
  24
  25 The callback-class must implement the interface `\wcf\system\bbcode\media\provider\IBBCodeMediaProvider`.
  26
  27 ### `<html>`
  28
  29 !!! warning "`<className>` and `<html>` are mutually exclusive."
  30
  31 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}`.
  32
  33 ## Example
  34
  35 {jinja{ codebox(
  36   title="mediaProvider.xml",
  37   language="xml",
  38   filepath="package/pip/mediaProvider.xml"
  39 ) }}