Tutorial: Build your own custom field plugin

You can download the files here:

https://www.github.com/coolcat-creations/plg_fields_owlimg.

Let's have a look at the folder structure of the plugin:

Folder structure:

• owlimg
  • owlimg.php
  • owlimg.xml
  • fields
    • owlimg.php
  • language
    • en-GB
      • en-GB.plg_fields_owlimg.ini
      • en-GB.plg_fields_owlimg.sys.ini
    • media
      • js
      • css
    • params
      • owlimg.php
  • tmpl
    • owlimg.php

owlimg.xml

To be able to install our plugin in Joomla! we must first create a manifest file in XML format.

Below I'll explain how this file is structured. But also have a look at the Joomla! documentation to deepen your knowledge: https://docs.joomla.org/Manifest_files

<?xml version="1.0" encoding="utf-8" ?>
<extension type="plugin" version="3.8" group="fields" method="upgrade">
	<name>plg_fields_owlimg</name>
	<author>Elisa Foltyn</author>
	<creationDate>09/2016</creationDate>
	<copyright>Copyright (C) 2017 Elisa Foltyn. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
	<authorEmail>joomla(at)coolcat-creations.com</authorEmail>
	<authorUrl>www.coolcat-creations.com</authorUrl>
	<version>1.0.0-alpha.1</version>

In the <extension> tag we define in the "type" attribute the extension type. In this case we are working on a Plugin. In the attribute "version" we define the minimum Joomla! version this plugin was made for. In the "group" attribute we define the plugin group. For Custom Fields the correct plugin group is "fields". In "method" we define the installation method. Using "upgrade" we make sure that we can install a newer version of the plugin in the future and Joomla! will not throw an error, that some of the files already exist.

In the next section of the XML File, in the so-called metadata, is the name of the plugin, the name of the author, the creation date, information about copyright and the license, the email address and the author's domain and the plugin version.

	<description>PLG_FIELDS_OWLIMG_XML_DESCRIPTION</description>

Now we can describe our plugin in the <description> tag. You see here the key PLG_FIELDS_OWLIMG_XML_DESCRIPTION. The specifications in the <description> and the <name> tag can contain language keys that can be translated in the files /owlimg/language/en-GB/en-GB.plg_fields_owlimg.sys.ini and /owl/language/en-GB/en-GB.plg_fields_owlimg.ini.

Why in both files?
The file with the suffix .sys.ini is used during the installation. The file ending with .ini is used afterwards.

	<files>
		<filename plugin="owlimg">owlimg.php</filename>
		<folder>fields</folder>
		<folder>language</folder>
		<folder>params</folder>
		<folder>tmpl</folder>
	</files>

Now we list in the <files> tag the files and folders, that belong to our plugin. We also define "owlimg" in the plugin attribute of the main file. 

	<media destination="plg_fields_owlimg" folder="media">
		<folder>js</folder>
		<folder>css</folder>
	</media>

In the next step we define the media folder so that Joomla! will copy the included files and folders into the plg_fields_owlimg folder inside the media directory. We can only do something like this for the media and language files.

If you want to move any other files or enable the plugin automatically after installation, you'll need to add a <scriptfile> tag with the path to a post-install-script.

For example: 

<scriptfile>plugins/fields/owlimg/script.php</scriptfile>

Example file: https://github.com/joomla-extensions/boilerplate/blob/master/plugins/system/script.php

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

Now we list our language files inside the <language> tag. These files will be moved into the language folder of the Joomla! installation. Do you remember? We already defined the language folder in the <files> tag. You can use both methods or one of them. The best is to read through the documentation for the manifest file to decide which will be best for you.

	<updateservers>
		<server type="extension" priority="1" name="Owl Image Carousel Joomla! Custom Field Update Site">https://raw.githubusercontent.com/coolcat-creations/plg_fields_owlimg/master/manifest.xml</server>
	</updateservers>

In the <updateserver> tag you define the path to the update manifest file. You can find a detailed description how to create an update server and how to create an update manifest file in the Joomla! documentation: https://docs.joomla.org/Deploying_an_Update_Server

A tutorial how to create a release on GitHub can be found here: https://help.github.com/articles/creating-releases/

	<config>
		<fields name="params">
			<fieldset name="basic">
				<field 
					name="layouthead"
					type="spacer" 
					label="PLG_FIELDS_OWLIMG_LAYOUTHEAD"
				/>

				<field
					name="items"
					type="number"
					label="PLG_FIELDS_OWLIMG_ITEMS"
					min="1"
					step="1"
					default="3"
				/>

...etc


			</fieldset>
		</fields>
	</config>

In the <config> tag we define the global field parameters. In this example we can specify how many images should be shown at once, if the animation should start automatically and more. An "Owl Carousel" can have several options. Take a look at the full owlimg.xml file in the downloaded folder. 

You can find an overview of all the possible owl options at this link:
https://owlcarousel2.github.io/OwlCarousel2/docs/api-options.html

</extension>

We close the </extension> tag at the end. We have now completed the installation file.