You are here:Home»KB»Web Design»CMS»Joomla»Extension Development»Creating a Joomla Plugin
Tuesday, 15 December 2015 22:44

Creating a Joomla Plugin

Written by

This tutorial is based on my GrabMeta Editor Button Plugin which I developed for myself. These instruction will be very similiar for a content plugin which I will address any differences at the end.

There are different types of plugins and I will list the ones I have created:

  • editors-xtdGrabMeta - This is also known as an editor button. The editor-xtd buttons are the buttons that are below the WYSIWYG and are independant of the WYSIWYG. When you press one of these buttons are pressed it executes code usually with the end result of content getting pasted into the WYSIWYG, but not always.
  • content - ExecuteCode - These plugins are run in the background during the page rendering process. The basic premisis is that they parse the page ($doc) and alter the text as per the plugins code. The new page is then passed tot he next plugin. These plugins tend only to affect the frontend page renders so the changes they make do not appear in the administrator section.
  • search - K2 Extended Search - A search plugin allows you to return results for the joomla search page

General Plugin

Basic Plugin File structure

/grabmeta/language/
/grabmeta/language/en-GB/
/grabmeta/language/en-GB/en-GB.plg_editors-xtd_grabmeta.ini
/grabmeta/language/en-GB/en-GB.plg_editors-xtd_grabmeta.sys.ini
/grabmeta/grabmeta.php
/grabmeta/grabmeta.xml
/grabmeta/index.html
/grabmeta/script.php

Plugin General Notes

  • when you zip up the file, it does not matter if all the file inside are inside 1 folder deep
  • for constructing a package (multiple extensions in 1 zip) see pkg_hs_highlighter_1.0.12
  • the plugin type can be derived from the folder name it sits in
  • TinyMCE plugin is great for plugin field types
  • Javascript does not like to be spread out over multiple lines so make sure you payload is all on 1 line.
  • If I POST to another file rather thand self, the javascript modal closers no longer work and the payload is not inserted. This must be because either the chain broken or the DOM reference is now incorrect.

Language

  • Language file naming conventions and precedence - http://docs.joomla.org/Specification_of_language_files
  • if you make a <description> to long it will create a link (in the plugin config) that says see full description and this takes you to the full description tab (which is also created to accommodate the full description)
  • a description has the html stripped out when used for the main config page and also in plugin lists etc.. in the joomla control panel, it is also truncated
  • upon installation the description, which is taken from en-GB.plg_editors-xtd_grabmeta.sys.ini description has the html stripped out, it is also truncated
  • there might be a way of {adding a readmore} to a description
  • when just using local language overrides the plugin will not be translated elsewhere in joomla ie plugin manager. PHP and JTEXT calls will still get translated
  • in the plugin folder, if you create a language folder and then put a language folder and file (specific to the language you are wanting to translate) in there it will overide the current language settings if you select that language. you do not need to set this file in you xml file. This is good for development as it prevents the need for you to keep re-installing the plugin to get the updated translations or having to edit those in the joomla system folders
     /grabmeta/ language/en-GB/en-GB.plg_editors-xtd_grabmeta.ini

It should be noted that I think if there are translation files in the joomla system folders they might take priority over the local override files

  • en-GB is the default language for joomla
  • you must reference a language file with <language> tag so the language files get installed to the appropriate joomla language folders
  • there are 2 main places for the language files to be installed, other than a local overide folder.
    /administrator/language/en-GB/ en-GB.plg_editors-xtd_grabmeta.ini
    /administrator/language/en-GB/ en-GB.plg_editors-xtd_grabmeta.sys.ini
  • the filename of the language determine where it goes
  • the sys file - en-GB.plg_editors-xtd_grabmeta.sys.ini - is the one that is required for outside plugin text translation
  • when specifying the language ini files, upon installation of the plugin, these files are moved
  • the xml file does not need to be indluded in the file references when you are using local language overide, but does for ini files that are getting installed.
  • language files are only referenced in the <languages> tag
  • when a language file is referenced in the xml (and thus installed correctely) you can have it any folder within your install package and it will allow translations.
  • en-GB.plg_editors-xtd_grabmeta.sys.ini controlls language for installation/lists external to the plugin ie plugin manager
  • en-GB.plg_editors-xtd_grabmeta.ini - controll most of the language, it can either be installed site wide in /administrator/language/en-GB/ or used as a local overide file in the plugin {plugin folder}/language/en-GB/ en-GB.plg_editors-xtd_grabmeta.ini
  • look at the file name of the ini file, it is important otherwise your translations will not work
  • if you do no specifiy the correct plugin group in the language file, it will not load. ie 'editors-xtd' in en-GB.plg_editors-xtd_grabmeta.sys.ini
    en-GB.plg_editors-xtd_grabmeta.sys.ini
    • en-GB – file language
    • plg – type of extension
    • editors-xtd – plugin type
    • .sys – if this is present the file is a system language file

Example language file references

<languages>
    <language tag="en-GB">language/en-GB/en-GB.plg_editors-xtd_grabmeta.ini</language>
    <language tag="en-GB">language/en-GB/en-GB.plg_editors-xtd_grabmeta.sys.ini</language>
</languages>
  • This example is using the local language override folders, you do not have to use these but it allows the installation success message (description from en-GB.plg_editors-xtd_grabmeta.sys.ini) to be displayed.
  • The tag="en-GB" denotes what language the files belong to and thus where they should be installed, not the file path of the files. So en-GB =
     /administrator/language/en-GB/
  • I have seen <languages folder="path/to/language"> but I am not sure of the purpose of this, it seems redundant now
  • You can use any folder location for language files as long as they are referenced correctely in your xml file. A lot of people use /language/ and put all the languages in here in one list

Sort these:

  • <folder> in plugins xml copies the whole folder and child files etc..
  • all videos has 2 tabs + description is fine <field set> creaes a new tab i think
  • a system plugin does not depend on a oncontentprepare() call. so this allows maipulation anywhere
  • the group=”” name can be gotton from the list of plugins in joomla via the plugin manager

Plugin Type Specific

editors-xtd (Editor Buttons)

Notes specific to an editor button, not address above should as the button calling code.

Button Function Examples

There are some slightly different ways to execute code via the editor button.

 Single Stage PHP

GrabMeta (AJAX /Multi Stage PHP)

  • Then buton when pushed loads a PHP file
  • This PHP file is has a form on it which you input data
  • When the form is submitted, the code is submitted back tot he PHP form for further processing
  • The results are then pasted into the WYSIWYG

Straight Button

  • A javascript is run directly from the button
  • no outside files or resources are use outside of the button script file (grabmeta.php)

Straight Button with Modal

  • A javascript is run inside a modal
  • no outside files or resources are use outside of the button script file (grabmeta.php)

Passing Variables

Whereever your active code is run from, you sometimes need to pass variables or information to it. There are 2 basic ways of doing that in Joomla:

  • $_GET style variables (Via the Button URL) -  These variables would be incorporated in to the button URL when the page is built so no interaction is possible with the data on the page. The primary use of this is to allow the plugin to read the settings from its config page to build an appropriate URL which will then performs the task to which it has been configured for.
  • Joomla database lookup - This would be used when you are loading a PHP script. This method allows completely independant data handling from the button. I have used this to lookup another plugin's settings and perform tasks appropriately. With this method you do not need to pass variables with $_GET from the button but it does take a little more setting up. You should use the Joomla Database Model (API) to read the information from the databse, but you can use a direct method of accessing the database if you wanted (only if you are desperate).

Content Plugin Specific

I will address the differences that are required for a content plugin

Language files

<languages>
    <language tag="en-GB">language/en-GB/en-GB.plg_content_executecode.ini</language>
    <language tag="en-GB">language/en-GB/en-GB.plg_content_executecode.sys.ini</language>
</languages>

As you can see the plugin type aspect fo the file name has changed, and in this case the name of the plugin. You can have 2 plugins, one button and one content with the same name such as 'executecode'.

XML file

  • the file name will now be executecode.xml
  • There are references in the XML file that will be different
Read 897 times Last modified on Sunday, 12 June 2016 09:34