J4.x

Creazione di un plugin per Joomla!

From Joomla! Documentation

This page is a translated version of the page J4.x:Creating a Plugin for Joomla and the translation is 100% complete.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Nederlands • ‎Türkçe • ‎español • ‎français • ‎italiano • ‎português do Brasil • ‎русский • ‎فارسی • ‎中文(台灣)‎
Tutorial
Come creare un plugin per Joomla 4
Joomla! 
4.x
series

La struttura del plugin per Joomla! 1.5, 2.5 e 3.x era molto flessibile e potente. Non solo i plug-in possono essere utilizzati per gestire gli eventi attivati dall'applicazione principale e dalle estensioni, ma i plug-in possono anche essere utilizzati per rendere estensibili e potenti estensioni di terze parti. In Joomla 4.x abbiamo riscritto molto del sistema di dispatcher per aumentare ulteriormente la flessibilità quando si modificano i parametri passati come eventi aumentando contemporaneamente le prestazioni dei plugin.

Questo How-To dovrebbe fornirti le basi di ciò che devi sapere per sviluppare il tuo plugin. La maggior parte dei plugin consiste in un solo file di codice, ma per installare correttamente il codice del plugin deve essere impacchettato in un file di installazione che può essere elaborato dal programma di installazione di Joomla.

Creazione del file di installazione

Come per tutte le estensioni in Joomla, i plugin sono facilmente installabili come file .zip (è supportato anche .tar.gz) ma deve essere incluso un file XML formattato correttamente.
Ad esempio, ecco il file di installazione XML per il plugin di ricerca per categorie:

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="search" method="upgrade">
	<name>plg_search_categories</name>
	<author>Joomla! Project</author>
	<creationDate>November 2005</creationDate>
	<copyright>Copyright (C) 2005 - 2018 Open Source Matters. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
	<authorEmail>admin@joomla.org</authorEmail>
	<authorUrl>www.joomla.org</authorUrl>
	<version>3.0.0</version>
	<description>PLG_SEARCH_CATEGORIES_XML_DESCRIPTION</description>
	<files>
		<filename plugin="categories">categories.php</filename>
	</files>
	<languages>
		<language tag="en-GB">en-GB.plg_search_categories.ini</language>
		<language tag="en-GB">en-GB.plg_search_categories.sys.ini</language>
	</languages>
	<config>
		<fields name="params">

			<fieldset name="basic">
				<field
					name="search_limit"
					type="number"
					label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
					default="50"
				/>

				<field
					name="search_content"
					type="radio"
					label="JFIELD_PLG_SEARCH_ALL_LABEL"
					layout="joomla.form.field.radio.switcher"
					default="0"
					>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>

				<field
					name="search_archived"
					type="radio"
					label="JFIELD_PLG_SEARCH_ARCHIVED_LABEL"
					layout="joomla.form.field.radio.switcher"
					default="0"
					>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>
			</fieldset>

		</fields>
	</config>
</extension>

Come puoi vedere, il sistema è simile ad altri file di installazione XML di Joomla. Devi solo cercare la voce group="xxx" nel tag <extension> e le informazioni estese nel tag <filename> . Queste informazioni indicano a Joomla in quale cartella copiare il file e in quale gruppo deve essere aggiunto il plugin

Se stai creando un plug-in che risponda agli eventi principali esistenti, l'attributo group="xxx" verrebbe modificato per riflettere il nome della cartella del plug-in esistente per il tipo di evento che desideri aumentare. ad es. group="authentication" o group="user". Vedi Plugin/Events per un elenco completo delle categorie di eventi principali esistenti. Nella creazione di un nuovo plug-in per rispondere agli eventi principali, è importante che il nome del tuo plug-in sia univoco e non sia in conflitto con nessuno degli altri plug-in che potrebbero rispondere anche all'evento principale che desideri servire.

Se stai creando un plug-in per rispondere a eventi di sistema non principali, la tua scelta per il tag group="xxx" dovrebbe essere diversa da qualsiasi delle categorie principali esistenti.

SUGGERIMENTO: se aggiungi l'attributo method="upgrade" al tag extension, questo plugin può essere installato senza disinstallare una versione precedente. Tutti i file esistenti verranno sovrascritti, ma i vecchi file non verranno eliminati.


Creazione del plug-in

In Joomla 4 puoi anche avere il codice namespace nel tuo plugin - leggi Namespace Conventions in Joomla 4. Nota che il file della voce principale non ha uno spazio dei nomi, ma i campi e qualsiasi altro codice di supporto lo sono

Il modo object-oriented di scrivere i plug-in prevede la scrittura di una sottoclasse di CMSPlugin, una classe base che implementa le proprietà di base dei plug-in. Nei tuoi metodi sono disponibili le seguenti proprietà:

  • $this->params: i parameters impostati per questo plugin dall'amministratore
  • $this->_name: il nome del plugin
  • $this->_type: il gruppo (tipo) del plugin
  • $this->db: l'oggetto db
  • $this->app: l'oggetto dell'applicazione

SUGGERIMENTO: per utilizzare $this->db e $this->app, CMSPlugin verifica se la proprietà esiste e non è privata. Se si desidera utilizzare gli oggetti predefiniti, creare proprietà non istanziate nella classe del plugin (ad es. protected $db; protected $app; nella stessa area di protected $autoloadLanguage = true;). Le proprietà non esisteranno se non esplicitamente create.

Nell'esempio di codice seguente, <PluginGroup> che rappresenta il gruppo (type) del plug-in e <PluginName> rappresenta il nome. Nota che i nomi delle classi e delle funzioni in PHP non fanno distinzione tra maiuscole e minuscole.

Qui implementiamo anche SubscriberInterface che è il cambiamento principale rispetto a Joomla 1.5-3.x. Invece di rilevare automaticamente il nome della funzione e coincidere con il nome dell'evento, ciò consente di avere nomi di funzione personalizzati. Questo ci consente di dire quali plug-in stanno implementando quali funzioni e poiché l'analisi dei metodi pubblici nel codice PHP è lenta, offre un notevole aumento delle prestazioni

Nota in tutta la serie Joomla 4 esiste un livello deprecato che coprirà i plug-in che utilizzano la vecchia strategia di denominazione dei nomi dei plug-in che sono gli stessi del nome dell'evento quando SubscriberInterface non è implementato

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

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\Event;
use Joomla\Event\SubscriberInterface;

class Plg<PluginGroup><PluginName> extends CMSPlugin implements SubscriberInterface
{
	/**
	 * Load the language file on instantiation
	 *
	 * @var    boolean
	 * @since  3.1
	 */
	protected $autoloadLanguage = true;

	/**
	 * Returns an array of events this subscriber will listen to.
	 *
	 * @return  array
	 */
	public static function getSubscribedEvents(): array
	{
		return [
			'<EventName>' => 'myFunctionName',
		];
	}

	/**
	 * Plugin method is the array value in the getSubscribedEvents method
	 * The plugin then modifies the Event object (if it's not immutable)
	 */
	 public function myFunctionName(Event $event)
	 {
		/*
		 * Plugin code goes here.
		 * You can access parameters via $this->params
		 */
		return true;
	}
}
?>


Usare i plugin nel tuo codice

Se stai creando un plug-in per un nuovo evento non principale, ricorda di attivare il plug-in dopo averlo installato. Precedi qualsiasi riferimento al tuo nuovo plugin con ilJPluginHelper::importPlugin().

Ora che hai creato il tuo plugin, probabilmente vorrai chiamarlo nel tuo codice. Potresti non farlo: il core di Joomla ha una serie di eventi integrati a cui potresti voler registrare il codice del tuo plugin (e in tal caso puoi ignorare questa sezione).

Nuovo modo Joomla 4

Il nuovo modo per farlo in Joomla 4 è ottenere il dispatcher e inviare un evento con nome

use Joomla\CMS\Event\AbstractEvent;
use Joomla\CMS\Factory;

$dispatcher = Factory::getApplication()->getDispatcher();

// Here we create an event however as long as you implement EventInterface you can create your own 
// custom classes
$event = AbstractEvent::create(
	'<EventName>',
	[
		'name' => $value,
	]
);

$eventResult = $dispatcher->dispatch('<EventName>', $event);

Se si desidera consentire all'utente di modificare i valori, è possibile utilizzare il risultato dell'evento e getResults da esso. Puoi guardare

defined('_JEXEC') or die;

use BadMethodCallException;
use Joomla\CMS\Event\AbstractImmutableEvent;
use Joomla\CMS\Table\TableInterface;

/**
 * Event class for an event
 */
class MyCustomEvent extends AbstractImmutableEvent
{
	/**
	 * Constructor.
	 *
	 * @param   string  $name       The event name.
	 * @param   array   $arguments  The event arguments.
	 *
	 * @throws  BadMethodCallException
	 */
	public function __construct($name, array $arguments = array())
	{
		if (!array_key_exists('myProperty', $arguments))
		{
			throw new BadMethodCallException("Argument 'myProperty' is required for event $name");
		}

		parent::__construct($name, $arguments);
	}

	/**
	 * Setter for the myProperty argument
	 *
	 * @param   mixed  $value  The value to set
	 *
	 * @return  mixed
	 *
	 * @throws  BadMethodCallException  if the argument is not of the expected type
	 */
	protected function setMyProperty($value)
	{
		if (!empty($value) && !is_object($value) && !is_array($value))
		{
			throw new BadMethodCallException("Argument 'src' of event {$this->name} must be empty, object or array");
		}

		return $value;
	}
}

Perché abbiamo introdotto questa classe di nomi sui parametri? Bene, semplifica l'introduzione di setter e getter personalizzati per le proprietà - attualmente un plug-in può modificare completamente una proprietà come vuole - per un componente non c'è modo di imporre alcuna limitazione. Inoltre, rende molto più facile per gli sviluppatori aggiungere e rimuovere parametri in un evento senza avere grossi b/c problemi (poiché ora stai chiamando metodi definiti e non sei soggetto a una proprietà come 2° argomento della tua funzione).

Come ottenere la massima compatibilità con Joomla 3

Se si desidera attivare un evento in modo simile al JEventDispatcher J3.x rimosso, utilizzare un codice come questo:

$results = \Joomla\CMS\Factory::getApplication()->triggerEvent( '<EventName>', <ParameterArray> );

È importante notare che i parametri devono essere in una matrice. La stessa funzione del plug-in otterrà i parametri come un Event object se implementa SubscriberInterface e come valori individuali in caso contrario, ma questo metodo restituirà sempre un array restituito dal plug-in

Si noti che se QUALSIASI plug-in in un gruppo non implementa SubscriberInterface, la proprietà del risultato (sia come parametro denominato che come risultato di un plug-in) viene utilizzata come proprietà speciale e non può essere utilizzata.