Make Your Own Plugin, Part 1: Plugin Components

If you've written a component that you think may be broadly usable for the QCubed community, it would be amazing if you took a few minutes to wrap it up nicely as a plugin - this would help everyone install your stuff easily, and who doesn't love it when their code is used and appreciated?

Writing a plugin is pretty simple. The first thing I'd do to learn about it is browse through the source code of one of the existing plugins to learn how it's been put together.

If you're ready to get started with your own plugin, create a directory somewhere on your computer; we'll refer to that directory as the "root" of your plugin. Add one file to the root: install.php. That configuration file will describe the steps that QCubed needs to take while installing, as well as uninstalling your plugin.

Then, create a few folders under the root, and place the files that you want to be distributed with the plugin there - the structure is entirely up to you. You may want to put all your included PHP files under the includes directory, or you may not; you can put all images in a separate folder, or just keep them as siblings of the configuration file.

A plugin is described through a QPlugin object - you can see all the properties of that object by inspecting the /includes/qcubed/_core/framework/QPluginInterface.class.php file. Take a look at it now.

To define the QPlugin object, we'll first set simple metadata on it:


				$objPlugin = new QPlugin();

				$objPlugin->strName = "MyCoolPlugin"; // no spaces allowed

				$objPlugin->strDescription = 'A great little plugin that does this and that';

				$objPlugin->strVersion = "0.1";

				$objPlugin->strPlatformVersion = "1.1"; // version of QCubed that this plugin works well with

				$objPlugin->strAuthorName = "Alex Weinstein, a.k.a. alex94040";

				$objPlugin->strAuthorEmail ="alex94040 [at] yahoo [dot] com";

Then, let's add QPluginFile's to the plugin. Each of the files that you added to the root folder will need to be mentioned, along with some relevant metadata for it, in order for that file to be deployed. Some of the plugin components you need to be aware of are:

QPluginControlFile: a class that extends QControl.
QPluginMiscIncludedFile: miscellaneous include file (non-web accessible).
QPluginCssFile, QPluginJsFile, QPluginImageFile: CSS, JavaScript, and image resources.
QPluginExampleFile: an example file for the plugin. Note that images, .tpl files, and other resources that are only used as a part of the example should all be declared as QPluginExampleFile's.

Let's now register several QPluginFiles with your QPlugin. Note that all paths are relative to the root of your plugin:


				$files = array(); 

				$files[] = new QPluginControlFile("includes/QPhoneTextBox.class.php");

				$files[] = new QPluginJsFile("js/phonetextbox.js");

				$files[] = new QPluginExampleFile("example/phonetextbox.php");

				$files[] = new QPluginExampleFile("example/phonetextbox.tpl.php");

				$objPlugin->addComponents($files);

After you've added all the files, it's time to declare any classfiles that need to be included when QCubed attempts to instantiate your plugin. You can do this by adding a QPluginIncludedClass component to your QPlugin:


				$components = array(); 

				// First parameter is the name of the class, second - path to the file, 

				// relative to the root of your plugin. Note that the QFile for this included

				// class should already be declared above! 

				$components[] = new QPluginIncludedClass("QPhoneTextBox", "includes/QPhoneTextBox.class.php");

				$objPlugin->addComponents($components);

It's always a good idea to provide a few examples with your plugin. To do so, we will create QPluginExample components, and add them to our QPlugin:


				$components = array(); 

				// First parameter is the path to the file, relative to the root of your plugin.

				// Second parameter is the description of the example. 

				$components[] = new QPluginExample("example/phonetextbox.php", "Validate and format phone numbers");

				$objPlugin->addComponents($components);

Now, add a magical line to the end of the configuration file...


				$objPlugin->install();

..and you're done! Read the next chapter to learn about ways to package and distribute your plugin.