TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,125 @@
+
+.. include:: /Includes.rst.txt
+
+.. _feature-61799:
+
+===================================================
+Feature: #61799 - Improved handling of online media
+===================================================
+
+See :issue:`61799`
+
+Description
+===========
+
+Editors can now use YouTube and Vimeo videos (online media) just like any other file, organising them just like any
+other file in the file list and selecting them in element browser to use in a CE or any other record.
+Adding new online media files is done providing the URL to online media. The matching helper class will fetch the
+needed metadata and supply an image that will be used as preview if available.
+
+
+YouTube and Vimeo support
+-------------------------
+
+The core provides an `OnlineMediaHelper` and a `FileRenderer` class for YouTube and Vimeo.
+
+Adding YouTube videos can be done by providing a URL in one of the following formats (with and without http(s)://):
+
+- youtu.be/<code> # Share URL
+- www.youtube.com/watch?v=<code> # Normal web link
+- www.youtube.com/v/<code>
+- www.youtube-nocookie.com/v/<code> # youtube-nocookie.com web link
+- www.youtube.com/embed/<code> # URL form iframe embed code, can also get code from full iframe snippet
+
+Adding Vimeo videos can be done by providing a URL in one of the following formats (with and without http(s)://):
+
+- vimeo.com/<code> # Share URL
+- player.vimeo.com/video/<code> # URL form iframe embed code, can also get code from full iframe snippet
+
+
+Each renderer has some custom configuration options:
+
+
+YouTubeRenderer
+^^^^^^^^^^^^^^^
+
+* `bool autoplay` default = FALSE; when set video starts immediately after loading of the page
+* `int controls` default = 2; see `<https://developers.google.com/youtube/player_parameters#controls>`_
+* `bool loop` default = FALSE; if set video starts over again from te beginning when finished
+* `bool enablejsapi` default = TRUE; see `<https://developers.google.com/youtube/player_parameters#enablejsapi>`_
+* `bool showinfo` default = FALSE; show video title and uploader before video starts playing
+* `bool no-cookie` default = FALSE; use domain youtube-nocookie.com instead of youtube.com when embedding a video
+
+Example of setting the YouTubeRenderer options with the MediaViewHelper:
+
+.. code-block:: html
+
+    <!-- enable js api and set no-cookie support for YouTube videos -->
+    <f:media file="{file}" additionalConfig="{enablejsapi:1, 'no-cookie': true}" />
+
+
+VimeoRenderer
+^^^^^^^^^^^^^
+
+* `bool autoplay` default = FALSE; when set video starts immediately after loading of the page
+* `bool loop` default = FALSE; if set video starts over again from te beginning when finished
+* `bool showinfo` default = FALSE; show video title and uploader before video starts playing
+
+Example of setting the YouTubeRenderer options with the MediaViewHelper:
+
+.. code-block:: html
+
+    <!-- show title and uploader for YouTube and Vimeo before video starts playing -->
+    <f:media file="{file}" additionalConfig="{showinfo:1}" />
+
+
+Register your own online media service
+--------------------------------------
+
+For every service you need an `OnlineMediaHelper` class that implements `OnlineMediaHelperInterface` and a
+`FileRenderer` class (see #61800) that implements `FileRendererInterface`. The online media helper is responsible
+for translating the input given by the editor to a `onlineMediaId` that is known to the service. The renderer is
+responsible for turning the `onlineMediaId` to the correct HTML output to show the media item.
+
+The `onlineMediaId` is stored in a plain text file that only holds this ID. By giving this file a custom file extension
+TYPO3 knows which `OnlineMediaHelper` and `FileRenderer` belong to it. To further tell TYPO3 what kind of
+"file" (text, image, audio, video, application, other) this online media holds we also need to bind a custom mime-type to
+this file extension.
+
+With adding this custom file extension to `$GLOBALS['TYPO3_CONF_VARS']['SYS']['mediafile_ext']` (see `#69543 <Feature-69543-IntroducedGLOBALSTYPO3_CONF_VARSSYSmediafile_ext.rst>`_) your custom
+online media file can be used throughout the backend every where all media files are allowed.
+
+**Example of registering your own online media file/service:**
+
+.. code-block:: php
+
+    // Register your own online video service (the used key is also the bind file extension name)
+    $GLOBALS['TYPO3_CONF_VARS']['SYS']['fal']['onlineMediaHelpers']['myvideo'] = \MyCompany\Myextension\Helpers\MyVideoHelper::class;
+
+    $rendererRegistry = \TYPO3\CMS\Core\Resource\Rendering\RendererRegistry::getInstance();
+    $rendererRegistry->registerRendererClass(
+        \MyCompany\Myextension\Rendering\MyVideoRenderer::class
+    );
+
+    // Register an custom mime-type for your videos
+    $GLOBALS['TYPO3_CONF_VARS']['SYS']['FileInfo']['fileExtensionToMimeType']['myvideo'] = 'video/myvideo';
+
+    // Register your custom file extension as allowed media file
+    $GLOBALS['TYPO3_CONF_VARS']['SYS']['mediafile_ext'] .= ',myvideo';
+
+
+Override core Helper class with your own helper class
+-----------------------------------------------------
+
+The helper classed provided by the core use the `oEmbed` web service provided by YouTube and Vimeo to gather some basic
+metadata for the provided video urls. The upside is that you do not need an API user/key to use their webservice as these
+services are publicly available. But the downside is that the gathered info is kind of scarce. So if you have an API user/key
+for these services, you could create an own helper class which provides more meta data.
+
+.. code-block:: php
+
+    // Register your own online custom youtube helper class
+    $GLOBALS['TYPO3_CONF_VARS']['SYS']['fal']['onlineMediaHelpers']['youtube'] = \MyCompany\Myextension\Helpers\YouTubeHelper::class;
+
+
+.. index:: FAL, Backend, Frontend, PHP-API, LocalConfiguration