YouTube Plugin
A simple plugin for October CMS to embed YouTube videos and meta data into your page.
Specifying the YouTube API Key
You need a YouTube API key. It is possible to embed videos without one, but in order to fetch the description and other meta data, an API key is required. Get one here.
Embedding a Video
Simply add the video component onto your page. In the commponent's settings, specify the YouTube video ID. It can be found at the end of the link to a YouTube video. So for example for this video 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' the ID is 'dQw4w9WgXcQ'.
The component also has more options:
- Player Controls: Wether control elements for the video are displayed.
- Privacy Enhanced Mode: If you activate the privacy-enhanced mode, YouTube will not save information about the users on your website, unless they watch the video.
- Responsiveness: Wether the video should be fixed size specified by width and height, or responsive.
- Width & Height: The width and height of the video if it is not responsive. Otherwise they have no effect.
Backend Settigns
API key: The API key needs to be a valid YouTube API key.
Should errors be dispalyed?: The default markup includes a descriptive error message if one occurs. This can be disabled here.
Embed Video Without Additional Data
If you want to embed just the video, but without additional data, you can fork the component and remove everything except for the iframes. The plugin however still expects the API key, even though embedding videos is possible without.
If you don't want to specify the API key, you can copy and paste the iframe manually. See this. Notice, that you can also specify privacy enhanced mode and whether you want video controls to be displayed.
Documentation
General
The plugin embeds YouTube videos in an iframe element. The privacy enhanced mode and the player controls are encoded in the URL of the iframe.
Meta data such as title, description, date of publishing etc. are fetched each time the page is accessed before the page is rendered from the YouTube API v3. This requires you to specify an API key in the settings.
Avaiable Data
All meta data is avaiable in the video.data.xxx properties. The avaiable meta data (i.e. all data except the URL) is:
- title
- description
- channelTitle
- publishedAt
- tags: a list of strings
- thumbnails: a list of pictures
Errors
If an error occurs while fetching the meta data, e.g. an incorrect API key, then the following will happen:
- The video's
iframeitself will still be displayed. - If the settings allow it, an error message is shown on the page.
- All meta data strings default to an empty string.
Settings
- YouTube API Key: Specify the YouTube API key.
- Display Errors?: This setting decides whether the default component displays errors. More precisely, it determines whether the property
video.errorholds an error string. - Bootstrap Version: Choose true if you use Bootstrap 5.x. Choose false if you use Bootstrap 4.x. This setting makes sure that the correct CSS classes are added to the default component. Additionally, the
responsiveRatioproperty is fromatted like 16x9 in Bootstrap 5.x mode, but 16by9 in Bootstrap 4.x mode. This is also to ensure the correct CSS classes are added.
YouTube API Key Remarks
Getting an API key is free, however it you get only 100'000 points a day, and one request costs 1 point. So since we are not caching, it costs one point per video per website access. However, 100'000 points should be sufficient for most users.
If you restrict your API key to specific URLs, make sure your app.url setting is correct and your website's URL is whitelisted in the API restrictions. The plugin will set the app.url's value as the referer header, which Google uses.
Languages
- English
- German
- Slovenian, Thanks Haedaki!
TODO
Feel free to help with translations
Out Of Scope for Me
- cache video meta data
-
This plugin has not been reviewed yet.
-
| 1.5.1 |
Fix min PHP requirement. Specify OctoberCMS versions. Setting descriptions improvements. Jun 19, 2022 |
|---|---|
| 1.5.0 |
Bootstrap 5.x support. Aug 07, 2021 |
| 1.4.1 |
Update YouTube iframe. Aug 06, 2021 |
| 1.4.0 |
Add composer.json for compatibility with OctoberCMS 2. Aug 06, 2021 |
| 1.3.3 |
German and Slovene (thanks Haedaki) translation. Minor improvements in English translation. Oct 04, 2020 |
| 1.3.2 |
Minor code improvements. Oct 01, 2020 |
| 1.3.1 |
Fix in license file. Sep 09, 2020 |
| 1.3.0 |
Referer set properly, so YouTube API key can be restricted to specific URLs. Sep 08, 2020 |
| 1.2.4 |
Default markup now uses Bootstrap. Sep 08, 2020 |
| 1.2.3 |
Ready for release. Sep 08, 2020 |
| 1.2.2 |
Permission improvements. Sep 08, 2020 |
| 1.2.1 |
Proper localization. Sep 08, 2020 |
| 1.2.0 |
Downgrade required PHP version to 7.3.x (from 7.4.x). Sep 08, 2020 |
| 1.1.1 |
Replace \n with <br /> in description. Sep 08, 2020 |
| 1.1.0 |
Release. Sep 08, 2020 |
| 1.0.1 |
Initialize plugin. Sep 08, 2020 |