Developing Joomla! 3 Content Plugin – Youtube Video for Joomla Article

Category: Joomla
Developing Joomla! 3 Content Plugin – Youtube Video for Joomla Article

Anyone who is running a website based on Joomla! system knows that you cannot directly insert any html code into your page or article. For example, if you paste a youtube link into content area, the link will be perceived as a usual link and the video will not be displayed.

Youtube offers Embed option that gives you an iframe code that you can insert into your article, but as far as it’s an html code, when you save your article Joomla! will escape iframe and will not display Youtube video. This is because iframe is set to be restricted in TinyMCE editor plugin.

So for the solution – Joomla! Plugins come in handy.

Joomla! plugins are code that run in the background and are triggered by events. When you log onto your Joomla! website, an authentication plugin checks your login credentials and decides whether you should have access to the site or not. Plugins can be used to transform content, such as replacing a tag in article with Youtube video with iframe or Google map.

Plugins can be very powerful, you can also use plugins to override core code and change how Joomla! works.

Joomla! ships with a variety of core events, organised into groups. Each group represented as plugin types have respective events. Joomla! documentation has the full list.

We will build a content type plugin. This mostly refers to article contents but some extensions load content plugins too. Content plugins allow you to change the content before it is displayed on the website.

In this case we’ll make use of onContentPrepare event, in order to change output text before it’s displayed to the user.

onContentPrepare is the first stage in preparing content for output and is the most common point for content orientated plugins to do their work. Since the article and related parameters are passed by reference, event handlers can modify them prior to display. To read more about this event visit this page.

Our youtube plugin will let users to paste youtube video’s id from the URL into the content area of an article in the following format {youtube_id}CD8nrL8ttNl{/youtube_id} and later when the content will be loaded youtube video id will be replaced with an actual youtube video.

Let’s get started!

To start you first create a folder and name it plg_content_NAME in our case it’s plg_content_youtubevid. plg indicates that it’s a plugin, and content tells that it’s a content type plugin. Most common Joomla! plugin contains three files: youtubevid.xml, youtubevid.php and an index.html.

An xml file is used for plugin setup, as any other xml files that are included into Joomla! modules and components. The php file will contain our main logic that will turn a usual link into a Youtube video displayed in the article.

XML file:

<?xml version="1.0" encoding="UTF-8"?>
<extension version="3.0" type="plugin" group="content" method="upgrade">
	<name>Content – Youtube Video</name>
	<author>mrGott</author>
	<creationDate>December 2015</creationDate>
	<copyright>Copyright (C) 2015 mrGott. All rights reserved.</copyright>
	<license> http://www.gnu.org/licenses/gpl-3.0.html</license>
	<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
	<authorUrl>http://mrgott.com</authorUrl>
	<version>1.0.0</version>
	<description>This plugin will replace Youtube video id into Video player in iframe. Requires Joomla! 3.0 or greater. Don't forget to publish this plugin!</description>
	<files>
		<filename plugin="youtubevid">youtubevid.php</filename>
		<filename>index.html</filename>
	</files>
</extension>

Now if you take a look at the xml code you will notice that it starts by extension tag that tells Joomla! what kind of extension it is. In this case it's type=”plugin”. Version parameter indicates to minimum version required for this extension. Group attribute let’s Joomla! know that it’s a content type, and it’s the only attribute that won’t be seen in a module or a component.

The method="upgrade" is important to note. If you do not include this, then every time you install an upgrade version of the extension, the uninstall script will run and it will delete your existing data. That's not really a problem for this plugin as it doesn't have an associated database table, but it's a good idea to include it anyway in all your extensions.

Up next is the name tag that contains the name of our plugin. It is common to first indicate the type of plugin, then put dash and the name of the plugin.

The upcoming tags are pretty self explanatory so let’s jump straight to version. It’s is very important if you plan to release new versions and to share it publicly.

The files tag tells Joomla! all the files that this extension uses, in this case, we only have two files in addition to our installation XML file, the index.html file and the youtubevid.php file which is going to contain the code for our plugin.

In your plg_content_youtubevid folder create an index.html file with the following code:

<html><body bgcolor=”#FFFFFF”></body></html>

Now let’s get to the most important part of our plugin development. youtubevid.php will contain plugin’s logic and main code.

The empty standard template for Joomla! plugin is as follows:

<?php
// no direct access
defined( '_JEXEC' ) or die;

jimport('joomla.plugin.plugin');
 
class plgContentYoutubevid extends JPlugin {

	function plgContentYoutubevid( &amp;$subject, $params ) {
		parent::__construct( $subject, $params );
	}

	public function onContentPrepare($context, &$row, &$params, $page = 0) {
		
		// Do not run this plugin when the content is being indexed
		if ($context == 'com_finder.indexer') {
			return true;
		}
		
		if (is_object($row)) {
			return $this->yourCustomFunction($row->text, $params);
		}
		
		return $this->yourCustomFunction($row, $params);		
	}
 

	protected function yourCustomFunction(&$text, &$params) {

		/*
		 * Plugin code goes here.
		 * You can access database and application objects and parameters via $this->db,
		 * $this->app and $this->params respectively
		 */

		return true;
		
	}
}
?>

NOTE: The code above runs with Joomla 3 and above. As found in the documents, parameters $this->db, $this->app are not available to Joomla before 3.4 version. And the onContentPrepare function differs from the one found on Joomla Docs. The same reason here, this code supports any version above Joomla 3.0 and code at Joomla Docs supports only Joomla 3.4 and above.

If you take a closer look at plugin’s code you will notice the function onContentPrepare. This is an event that we mentioned earlier. Inside we have an if statement the checks whether the page has been loaded by Joomla’s smart search “com_finder” to be indexed or it’s a call by a user. If the user calls the page it will load the function that will contain your plugin’s code.

In our case it is a youtubeToVideo function that will call another custom function replaceYoutube. The code is as follows:

protected function replaceYoutube($videoId){

	$replaceString = '<div class="videowrapper">
		<iframe width="560" height="315" src="https://www.youtube.com/embed/' . $videoId . '" frameborder="0" allowfullscreen></iframe>
		</div>';

	return $replaceString;
}

protected function youtubeToVideo(&$text, &$params) {

	$tagname = "youtube_vid";

	$pattern = "#{\s*?$tagname\b[^}]*}(.*?){/$tagname\b[^}]*}#s";

	$text = preg_replace($pattern, $this->replaceYoutube('$1'), $text);

	return true;
}

The main logic of our plugin is to search the $text of the content before it’s loaded, find the specific pieces and replace them with an iframe.

In more detail, we use php function preg_replace that takes three parameters. $pattern is a REGEX expression that we trying to match inside the $text and the call to the function replaceYoutube is a code that we want to replace all matches found in the $text.

In many cases you will find that the replacement is written inside the main function that has been triggered by an event, in our case it’s youtubeToVideo, but I prefer separating code in many independent pieces. So if I wanted to do another replacement, instead of the iFrame, I would mess up with my main code, and do all changes in the replaceYoutube function.

Conclusion

So this is it. Now you are ready to zip your plugin and install on you Joomla. If you are looking for adding some parameters to your plugin, visit Joomla Documentation. In case you want to know more about REGEX I discovered a good blog post and you can find a link to it below.