Tutorial: Erstelle ein eigenes Custom Field Plugin

Du kannst dir die Dateien zu diesem Plugin unter
https://www.github.com/coolcat-creations/plg_fields_owlimg herunterladen.

Zunächst sehen wir uns die Ordnerstruktur des Plugins an:

Ordnerstruktur:

• 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

Um unser Plugin bei Joomla überhaupt installieren zu können, erstellen wir zunächst eine Manifest Datei im xml Format.

Ich erkläre dir nachfolgend kurz wie sich diese Datei aufbaut, sehe dir am besten auch bei der Joomla! Dokumentation den folgenden Beitrag an, um dein Wissen zu vertiefen: 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>

Wir definieren im <extension> Tag mit dem "type" Attribut den Erweiterungstypen, der in diesem Fall ein Plugin ist. Im Attribut "version" wird die Joomla! Version definiert, für die das Plugin entwickelt wurde. Das "group" Attribut benennt die Plugin Gruppe, die im Fall von einem Custom Fields Plugin "fields" ist und unter "method" wird die Installationsmethode bestimmt. Mit "upgrade" stellen wir sicher, dass wir jederzeit das Plugin "drüberinstallieren" können und Joomla nicht meldet, dass Verzeichnisse bereits existieren.

Im nachfolgenden Teil der XML Datei, in den sogenannten Metadaten steht der Name des Plugins, Angaben zum Autoren, das Erstellungsdatum, Angaben zum Copyright, ein Hinweis zur Lizenz, die Email-Adresse des Autors, die Domain des Autors und die Version des Plugins.

	<description>PLG_FIELDS_OWLIMG_XML_DESCRIPTION</description>

Nun beschreiben wir unser Plugin im <description> Tag. Du siehst hier die Sprachkonstante PLG_FIELDS_OWLIMG_XML_DESCRIPTION. Die Angaben in den Tags <description> und <name> können Sprachkonstanten enthalten und in der Datei /owlimg/language/en-GB/en-GB.plg_fields_owlimg.sys.ini und /owl/language/en-GB/en-GB.plg_fields_owlimg.ini übersetzt werden.

Warum in beiden Dateien?
Die Datei mit der Endung .sys.ini wird beim Installationsvorgang verwendet. Die Datei mit der Endung .ini im laufenden Betrieb.

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

Im <files> Tag werden die Dateien und Ordner gelistet die zu unserem Plugin gehören, darin definieren wir für unsere Hauptdatei, die das Plugin aufruft, noch das plugin Attribut.

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

Im nächsten Schritt definieren wir den Media Ordner und weisen Joomla! dazu an, die im darin befindlichen Dateien in den Ordner plg_fields_owlimg in den media Ordner zu verschieben. Ein solches Vorgehen ist nur für den Media Ordner und für die Sprachdateien möglich.

Wenn man andere Dateien verschieben möchte, oder das Plugin nach der Installation automatisch aktivieren will, dann muss man im <scriptfile> tag ein Post-Install Script definieren.

Zum Beispiel: 

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

Beispieldatei: 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>

Im <language> Tag listen wir die Sprachdateien auf, die wir mit dem Plugin mitliefern. Diese Dateien werden dann in den language Ordner der Joomla! Installation kopiert. Erinnerst du dich? Wir haben den Ordner languages auch im <files> tag definiert. Du kannst eine der beiden Methoden nutzen oder auch beide zusammen. Nähere Informationen zu den Vor- und Nachteilen findest du in der Dokumentation zur Manifest Datei.

	<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>

Im <updateserver> Tag wird der Pfad zur Update-Manifestdatei festgelegt. Eine Anleitung wie man einen Update Server und eine Update Manifest Datei anlegt, findest du in der Joomla! Dokumentation unter: https://docs.joomla.org/Deploying_an_Update_Server

Eine Anleitung wie man ein Release auf GitHub vorbereitet findest du hier: 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>

Im <config> Tag definieren wir die globalen Feldparameter. Für das "Owl Carousel" können wir hier Parameter definieren, in denen wir einstellen können, wie viele Bilder im Carousel dargestellt werden sollen, ob die Animation automatisch starten soll, ob eine Navigation angezeigt werden soll oder nicht. Ein Owl Carousel kann verschiedene Optionen haben. Sehe dir die vollständige owlimg.xml Datei im Downloadpaket einfach mal näher an.

Für eine Übersicht der möglichen Owl-Funktionen sehe dir diesen Link an:
https://owlcarousel2.github.io/OwlCarousel2/docs/api-options.html

</extension>

Und zum Schluss schließen wir den <extension> Tag. Unsere Installationsdatei ist somit fertig.