How to use the Joomla Content Plugin CCC External Video Preview
CCC External Video Preview shows YouTube and Vimeo videos as a preview that only loads on click. This guide takes you from installation to connecting a cookie banner.
Step 1: Installation
Install the plugin: Upload the package in the Joomla backend under System → Install → Extensions. The plugin is enabled right away; you will find it under System → Plugins as “Content - CCC External Video Preview”.
Requirements: Joomla 4.4 or newer (developed and tested with Joomla 6) and PHP 8.1 or newer.
Step 2: Enter your download key
Enable updates: Open System → Update Sites, select the entry “plg_content_cccexternalvideopreview” and enter your download key there. Without the key Joomla still shows new versions but cannot download them.
Step 3: Add a video
The plugin works wherever Joomla runs content plugins: in articles, in Custom modules with Prepare Content enabled, and in page builders. Put one of the following shortcodes where the video should appear:
{youtube}dQw4w9WgXcQ{/youtube}– a YouTube video by its ID{youtube}https://youtu.be/dQw4w9WgXcQ?t=90{/youtube}– a YouTube video by its full address; the start time is taken over{vimeo}76979871{/vimeo}– a Vimeo video by ID or address{video}https://vimeo.com/76979871{/video}– recognises YouTube and Vimeo by the address
The usual addresses are accepted: watch, share, embed and Shorts links from YouTube as well as video and player links from Vimeo. Anything that is not recognised as a YouTube or Vimeo video is left exactly as it is.
Step 4: Settings for a single video
Settings for a single video go into the opening tag and take precedence over the plugin settings:
{youtube start=30 width=640 title="Product tour"}dQw4w9WgXcQ{/youtube}
title– title of the video, for screen readers and as the title of the playerstart– start time in secondswidth,height– size in pixels;widthlimits the widthratio– aspect ratio, for example4:3or9:16autoplay,fullscreen–1or0nocookie,related– YouTube only,1or0dnt,private-hash– Vimeo onlyimage– your own preview image (path or address)text– your own text instead of “Click to load the video.”play-button– your own play buttonclass– additional CSS class
Step 5: Convert existing embeds and links
Convert existing embeds: With this setting enabled, the plugin replaces YouTube and Vimeo iframes that are already in your content with the preview. You do not have to edit a single article. Other iframes are left untouched. On a new installation the setting is switched on.
Convert video links: Turns a YouTube or Vimeo address into a preview when it is the only content of a paragraph. Links inside running text stay normal links. This setting is switched off at first.
Step 6: Set up player and preview
“Player” tab: Decide whether the clicked video starts right away, whether fullscreen is allowed, whether YouTube videos are loaded in privacy-enhanced mode (www.youtube-nocookie.com) and whether Vimeo is asked not to track playback.
“Preview” tab: The plugin downloads the preview image of each video to your server once and delivers it from there. You decide after how many days it is refreshed, which fallback image is shown, whether the image is blurred, what the play button looks like and whether the notice sits below or on top of the preview image. Background colour, padding and border of the notice are set here as well.
Step 7: Privacy link and consent
Link to your privacy policy: On the “Privacy” tab you select an article, a menu item or an address. On multilingual sites one article or menu item is enough: for the other languages the plugin uses its language associations.
Remember the visitor's choice: Once a visitor has loaded a video, further videos of the same platform load without asking again. You choose whether this lasts until the browser tab is closed, permanently, or not at all. The choice is stored in the visitor's browser only, not on the server and not in a cookie. Below every loaded video there is a link the visitor can use to remove the connection again.
Step 8: Change texts and appearance
Texts: All texts visitors see can be changed under System → Language Overrides. The keys start with PLG_CONTENT_CCCEXTERNALVIDEOPREVIEW_, for example PLG_CONTENT_CCCEXTERNALVIDEOPREVIEW_PRIVACY_TEXT for the privacy notice.
Appearance with CSS: Colours, radius and spacing are CSS custom properties. Override them in your template's CSS without replacing any of the plugin's rules:
.cccyt-wrapper {
--cccyt-radius: 12px;
--cccyt-privacy-bg: #eef3f8;
--cccyt-privacy-color: #1a1a1a;
--cccyt-focus-color: #005fcc;
}Your own markup: Copy the file plugins/content/cccexternalvideopreview/tmpl/placeholder.php to templates/YOUR_TEMPLATE/html/plg_content_cccexternalvideopreview/placeholder.php and adjust it there. If your template styles the preview completely on its own, you can switch off the plugin styles on the “Preview” tab.
Step 9: Connect a cookie banner or consent tool
If a consent tool manages the consents of your website, it can tell the plugin when videos may be loaded. There is a small JavaScript API for this:
CccExternalVideoPreview.accept('youtube'); // load all YouTube videos
CccExternalVideoPreview.revoke('youtube'); // withdraw the consent
CccExternalVideoPreview.hasConsent('vimeo'); // true or false
CccExternalVideoPreview.init(element); // include content added later
In addition the plugin fires the events cccevp:activated and cccevp:reset, each with the platform and the video ID.