[DOCS] 7.5 Docs Part 10
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 7.5 / Feature-61799-ImprovedHandlingOfOnlineMedia.rst
1 ===================================================
2 Feature: #61799 - Improved handling of online media
3 ===================================================
4
5 Description
6 ===========
7
8 Editors can now use YouTube and Vimeo videos (online media) just like a any other file, organising them just like any
9 other file in the file list and selecting them in element browser to use in a CE or any other record.
10 Adding new online media files is done providing the URL to online media. The matching helper class will fetch the
11 needed metadata and supply an image that will be used as preview if available.
12
13
14 YouTube and Vimeo support
15 -------------------------
16
17 The core provides an ``OnlineMediaHelper`` and a ``FileRenderer`` class for YouTube and Vimeo.
18
19 Adding YouTube videos can be done by providing a URL in one of the following formats (with and without http(s)://):
20
21 - youtu.be/<code> # Share URL
22 - www.youtube.com/watch?v=<code> # Normal web link
23 - www.youtube.com/v/<code>
24 - www.youtube-nocookie.com/v/<code> # youtube-nocookie.com web link
25 - www.youtube.com/embed/<code> # URL form iframe embed code, can also get code from full iframe snippet
26
27 Adding Vimeo videos can be done by providing a URL in one of the following formats (with and without http(s)://):
28
29 - vimeo.com/<code> # Share URL
30 - player.vimeo.com/video/<code> # URL form iframe embed code, can also get code from full iframe snippet
31
32
33 Each renderer has some custom configuration options:
34
35
36 YouTubeRenderer
37 ^^^^^^^^^^^^^^^
38
39 * ``bool autoplay`` default = FALSE; when set video starts immediately after loading of the page
40 * ``int controls`` default = 2; see `<https://developers.google.com/youtube/player_parameters#controls>`_
41 * ``bool loop`` default = FALSE; if set video starts over again from te beginning when finished
42 * ``bool enablejsapi`` default = TRUE; see `<https://developers.google.com/youtube/player_parameters#enablejsapi>`_
43 * ``bool showinfo`` default = FALSE; show video title and uploader before video starts playing
44 * ``bool no-cookie`` default = FALSE; use domain youtube-nocookie.com instead of youtube.com when embedding a video
45
46 Example of setting the YouTubeRenderer options with the MediaViewHelper:
47
48 .. code-block:: html
49
50     <!-- enable js api and set no-cookie support for YouTube videos -->
51     <f:media file="{file}" additionalConfig="{enablejsapi:1, 'no-cookie': true}" />
52
53
54 VimeoRenderer
55 ^^^^^^^^^^^^^
56
57 * ``bool autoplay`` default = FALSE; when set video starts immediately after loading of the page
58 * ``bool loop`` default = FALSE; if set video starts over again from te beginning when finished
59 * ``bool showinfo`` default = FALSE; show video title and uploader before video starts playing
60
61 Example of setting the YouTubeRenderer options with the MediaViewHelper:
62
63 .. code-block:: html
64
65     <!-- show title and uploader for YouTube and Vimeo before video starts playing -->
66     <f:media file="{file}" additionalConfig="{showinfo:1}" />
67
68
69 Register your own online media service
70 --------------------------------------
71
72 For every service you need an ``OnlineMediaHelper`` class that implements ``OnlineMediaHelperInterface`` and a
73 ``FileRenderer`` class (see #61800) that implements ``FileRendererInterface``. The online media helper is responsible
74 for translating the input given by the editor to a ``onlineMediaId`` that is known to the service. The renderer is
75 responsible for turning the ``onlineMediaId`` to the correct HTML output to show the media item.
76
77 The ``onlineMediaId`` is stored in a plain text file that only holds this ID. By giving this file a custom file extension
78 TYPO3 knows which ``OnlineMediaHelper`` and ``FileRenderer`` belong to it. To further tell TYPO3 what kind of
79 "file" (text, image, audio, video, application, other) this online media holds we also need to bind a custom mime-type to
80 this file extension.
81
82 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
83 online media file can be used throughout the backend every where all media files are allowed.
84
85 **Example of registering your own online media file/service:**
86
87 .. code-block:: php
88
89     // Register your own online video service (the used key is also the bind file extension name)
90     $GLOBALS['TYPO3_CONF_VARS']['SYS']['OnlineMediaHelpers']['myvideo'] = \MyCompany\Myextension\Helpers\MyVideoHelper::class;
91
92     $rendererRegistry = \TYPO3\CMS\Core\Resource\Rendering\RendererRegistry::getInstance();
93     $rendererRegistry->registerRendererClass(
94         \MyCompany\Myextension\Rendering\MyVideoRenderer::class
95     );
96
97     // Register an custom mime-type for your videos
98     $GLOBALS['TYPO3_CONF_VARS']['SYS']['FileInfo']['fileExtensionToMimeType']['myvideo'] = 'video/myvideo';
99
100     // Register your custom file extension as allowed media file
101     $GLOBALS['TYPO3_CONF_VARS']['SYS']['mediafile_ext'] .= ',myvideo';
102
103
104 Override core Helper class with your own helper class
105 -----------------------------------------------------
106
107 The helper classed provided by the core use the ``oEmbed`` web service provided by YouTube and Vimeo to gather some basic
108 metadata for the provided video urls. The upside is that you do not need an API user/key to use their webservice as these
109 services are publicly available. But the downside is that the gathered info is kind of scarce. So if you have an API user/key
110 for these services, you could create an own helper class which provides more meta data.
111
112 .. code-block:: php
113
114     // Register your own online custom youtube helper class
115     $GLOBALS['TYPO3_CONF_VARS']['SYS']['OnlineMediaHelpers']['youtube'] = \MyCompany\Myextension\Helpers\YouTubeHelper::class;