Table of Contents

Introduction

The Related YouTube Videos plugin allows you to easily embed YouTube videos that automatically relate to your content in one way or another by using a simple shortcode [relatedYouTubeVideos] or a widget.

You can specify if the relation is by post title, post tags, post categories, or by using your own custom keywords.

top

 

Settings

Load CSS theme file in the frontend.

If this option is checked an additional CSS file will be loaded when visiting the frontend of your website. If you want to use the out-of-the-box themes or styles that are being provided by this plugin you will have to do this!

Yes, it's an additional HTTP request that needs to be made. But the current CSS file is minified and currently under 1KB(!) so you really shouldn't obsess over it.

This CSS file also contains a basic reset! Since the HTML for embedding the videos is an unordered list, this reset will remove the typical list elements (dots, discs, or squares, etc).

Default Relation.

You can select the default relation to be post title, post tags, post categories, or custom keywords. So in case you either don't (want to) set the relation parameter or the value contains none of these types, this default will be used.

top

 

Parameters

The parameters you can use to customize the related videos are the same for the shortcode as well as the widget.

While you already have input fields in the widget settings you have to add parameters to the shortcode in the form of parameter="{value}".
For example: [relatedYouTubeVideos relation="postTags" max="3" class="horizontal center bg-black"]

Of course you can add multiple parameters to a single shortcode. But be aware that paramters are case-sensitive!

Appearance
id HTML id attribute that will be added the HTML list element <ul> that contains the videos.
class HTML class attribute. You can add your own classes here (multiples separated by a space character). If you want to your the themes/styles coming with this plugin you basically add one or more pre-defined classes here.
width Numeric width of the videos in pixels.
height Numeric height of the videos in pixels.
preview Can either be set to true or left out completly (which equals false).
preview="true" will show an image first and only when clicking this image the actual video will be loaded and played. This will make your page(s) load faster since videos tend to block the process of rendering the rest of the page but it requires Javascript to be enabled in a user's browser.
showVideoTitle Can either be set to true or left out completly (which equals false).
viewVideoTitle="true" will show the title of the video given by the uploader.
showVideoDescription Can either be set to true or left out completly (which equals false).
viewVideoDescription="true" will show the description of a video given by the uploader.
Configuration
max Number of videos to show.
max="2" will show you 2 videos.
random You can also show random videos to make it more interesting for visitors of your site. The number you set here will determine the pool size from which max random videos will be show.
max="2" random="10" will show 2 random videos from a pool of 10.
offset Number of videos to skip from the beginning of the results coming from YouTube. If used it has to be > 0.
offset="2" will skip the first two results and start showing videos form position 3 on.
YouTube
relation Can either be set to postTitle, postTags, postCategories, or keywords (in which case you will also have to set the terms parameter).
relation="postTags" will search YouTube for videos matching a blog posts list of tags. The default, like when you don't specify any relation at all or have a typo in it, is postTitle.
terms Here, you can specify custom keywords all by yourself - in case of relation="keywords".
relation="keywords" terms="monty python" will show Monty Python videos, no matter what the post title or the tags or the categories say.
exact Can either be set to true or left out completly (which equals false).
exact="true" will search YouTube for exact matches for your post title, tags, categories or custom keywords. An exact search is like when you wrap your search terms into quotation marks.
orderBy Can either be relavance, published, rating, or viewCount. If it's not set relevance will be used as default.
orderBy="rating" will show videos with the best ratings amongst the search results.
lang Two-letter language code. Will only show videos in that language, if possible.
lang="fr" will only show videos in french. You can also exclude all other languages by using this parameter.
region Two-letter country code. Will only show videos that are actually viewable in the given region/country.
region="de" will only show videos viewable (= not blocked) in Germany.
author Only show videos uploaded from a given YouTube username.
author="meomundodotcom" will only show videos from the YouTube user meomundodtocom.
filter Add additional keywords or filtering search parameters. This might be usefull if your relation is title, tags, or categories. In case of keywords you could add these filters to your keywords directly.
filter="intitle:official -intitle:cover -intitle:lyrics" will (hopefully) only show the official music video and no cover version or lyrics slideshow.
You can also manually add the post title, tags, and/or categories by adding +postTags, +postCategories, and/or +postTitle to your filter.
E.g. if relation="postTitle" and might use filter="+postCategories" to search YT.
viewRelated Show more related videos at the end of a clip - or not!
viewRelated="no" will not show more related videos at the enf of a clip.

top

 

Themes / Styles

If you allow to load the plugin's theme CSS file you can add one or more of the following classes to the class parameter, separated by a space character, in case you want to combine multiple ones.

Of course you can use your own CSS formatting but maybe it's easier to use some of the pre-defined styles.

left Lets the video container float left and therefore the surrouding text right next to it.
class="left"
right Lets the video container float right and therefore the surrouding text left next to it.
class="right"
center If more than one video is show they will be centered within the container element.
class="right"
inline
horizontal
Will show videos inline instead of underneath one another.
class="horizontal"
bg-black Sets the background color of the video container to black and the text color (video title and description) to white.
class="bg-black"
bg-white Sets the background color of the video container to white and the text color (video title and description) to black.
class="bg-black"
spacing-5
spacing-10
spacing-15
spacing-20
spacing-25
Will create a 5, 10, 15, 20, or 25 pixels space around each video.
class="spacing-10"

Combined example: [relatedYouTubeVideos relation="postTitle" max="5" lang="en" class="left horizontal bg-black center" previewMode="true"]

top

 

API

If you want to you can hard-code the related videos directly into your theme, respectively the page or post tempaltes of your theme. To do so you should use the following PHP code:


<?php
/* Load the "Related YouTube Videos" API class if it does not exist yet. */
if( !class_exists( 'RelatedYouTubeVideos_API' ) ) {

  $file = str_replace( '/', DIRECTORY_SEPARATOR, ABSPATH ) . 'lib' . DIRECTORY_SEPARATOR . 'RelatedYouTubeVidoes' . DIRECTORY_SEPARATOR . 'API.php';

  if( file_exists( $file ) ) {
    
    include_once $file;
    
  }

}
/* Only continue if the API class could be loaded properly. */
if( class_exists( 'RelatedYouTubeVideos_API' ) ) {

  $RytvAPI  = new RelatedYouTubeVideos_API();
  
  /* Do your configuration */
  $data     = $RytvAPI->validateConfiguration(
    array(
     'relation' => 'postTitle',
     'max'      => '3',
     'width'    => 150,
     'height'   => 150,
     'lang'     => 'en',
     'region'   => 'de',
     'class'    => 'left center inline bg-black',
     'preview'  => true
    )
  );

  /* Search YouTube. */
  $results  = $RytvAPI->searchYouTube( $data );

  /* Generate the unordered HTML list of videos according to the YouTube results and your configuration.  */
  $html     = $RytvAPI->displayResults( $results, $data );
  
  echo $html; // Or do with it whatever you like ;)

}
?>

top

 

Credits

If you have any questions or requests which might be usefull to others as well please post them on wordpress.org/support/plugin/related-youtube-videos. Or you can contact me directly via meomundo.com.

I'd also like to thank Borisa Djuraskovic for providing the Serbo-Croatian translation.

Oh, and if you like this plugin it would be nice of you to give it a little rating (in the sidebar), thx :)

top