LinuxParty

Descripción

Hay muchas habilidades para el uso de un complemento de contenido. Todos tienen que ver con la visualización de su contenido y con sus artículos. Necesitará al menos dos archivos para este complemento. Un archivo XML y un archivo PHP. Debido a que hay tantas diferencias entre dos complementos de contenido en el archivo PHP, se explicarán dos ejemplos de ellos en este documento. También se agrega una parte sobre internacionalización (con archivos INI). Y por último pero no menos importante: el Joomla! Ejemplos de codificación de Core Content Plugin y consejos rápidos.

Archivo XML

El archivo XML tiene el mismo nombre que el archivo PHP y es uno de los dos archivos necesarios. Comience siempre con la etiqueta XML y defina que está escrita en formato UTF-8.

<?xml version="1.0" encoding="utf-8"?>

Para definir que el complemento tiene que ser un complemento de contenido, agregue esta línea:

<extension version="3.1" type="plugin" group="content">

El tipo lo definirá como un complemento, el grupo define que el complemento está en el grupo de complementos de contenido.

Después de eso, agregue información sobre usted y el complemento, de esta manera:

<name>Nombre de su complemento de contenido</name> 
<creationDate>Fecha de creación</creationDate> 
<author>Su nombre</author> 
<authorEmail>Su dirección de correo electrónico</authorEmail> 
<authorUrl>Su sitio web</authorUrl> 
<copyright> Copyright </copyright> 
<license> Licencia, por ejemplo GNU/GPL </license> 
<version> Versión del complemento </version> 
<description> Descripción del complemento; mostrado con la instalación y al editar
el complemento en el Administrador de complementos </description>

Y ahora incluya su archivo PHP en el complemento de contenido. El nombre de este archivo debe ser el mismo que el de este archivo XML. Pon este nombre también detrás de la parte plugin = "".

También puede agregar más archivos para su complemento, por ejemplo, una imagen. Simplemente agregue otra fila entre <files> y </files>, y luego coloque el archivo entre las etiquetas <filename>.

<files>
   <filename plugin="nameofplugin">nameofplugin.php</filename>
</files>

Algunos archivos, como .js o .css, no se reconocen y causarán un error cuando intentes instalar el complemento. Para estos, simplemente cree una nueva carpeta en el directorio de complementos, luego agregue los archivos a la carpeta. Luego agregue una línea para la carpeta en las etiquetas <files>. Por supuesto, los archivos .js y .css podrían administrarse mejor como parte de la plantilla, pero si estos son específicos del complemento, entonces podrían ir aquí.

<files>
   <folder>scripts</folder>
   <folder>css</folder>
</files>

Para la internacionalización, utilizaremos archivos de idioma. Esto no es obligatorio, pero a las personas de otros países les encantará si pueden traducir fácilmente su complemento a su propio idioma. La ubicación recomendada para los archivos de idioma está dentro de su extensión. Los archivos de idioma se almacenan en un directorio de "idioma" en su nombre de plugin / language / xx-XX / donde xx-XX es el código de un idioma que utilizará Joomla. (Anteriormente, los archivos de idioma se guardaban en varios lugares alrededor de su instalación de Joomla, puede leer más sobre los archivos de idioma en el artículo Manifiesto.

Las etiquetas de idioma se pueden encontrar aquí: [1] (use la columna ISO 639-1) y aquí: [2]

Cuando agregue la carpeta de idioma a sus archivos, use la etiqueta <folder>, de modo que al expandir en el ejemplo anterior, su etiqueta <files> se vería así:

<files>
   <folder>scripts</folder>
   <folder>css</folder>
   <folder>language</folder>
</files>

Opcionalmente, puede agregar algunos parámetros al complemento. Estos se verán así:

<config>
	<fields name="params">
		<fieldset name="basic">
			<field name="field1" type="text"
				description="Example field 1"
				label="Example field 1"
			/>
		</fieldset>
	</fields>
</config>

• Nombre de campo: el nombre del parámetro. Lo necesitará al crear el archivo PHP.
• Tipo de campo: puede elegir entre varios tipos de parámetros. Mire este documento para aprender algo sobre los diferentes tipos: Diferentes campos de formulario de Joomla
• Valor predeterminado de campo: la configuración predeterminada para este parámetro.
• Etiqueta de campo: el nombre de este parámetro que se muestra en la pantalla de edición de este complemento en el Administrador de complementos.
• Descripción del campo: el texto que aparece como información sobre herramientas para este parámetro.

Cuando no desee utilizar parámetros, agregue la siguiente etiqueta:

<config />

Y no olvide finalizar su archivo XML con la siguiente etiqueta:

</extension>

Archivo PHP

Inicie su archivo PHP con la licencia general y la información del autor sobre su complemento de contenido.

<?php 
/ ** 
* @version $ Id: nameofplugin.php fecha de revisión (la que fuera) $ 
* @package Joomla 
* @Subpackage Content 
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. Todos los derechos reservados. 
* @license GNU / GPL, ver LICENCIA.php 
* Joomla! es software libre Esta versión puede haber sido modificada de acuerdo con 
* a la Licencia Pública General de GNU, y tal como se distribuye incluye o 
* es derivado de obras con licencia bajo la Licencia Pública General de GNU u 
* otras licencias de software de código abierto o gratuito. 
* Ver COPYRIGHT.php para avisos de copyright y detalles. 
* /

A continuación, siempre coloque el siguiente código en cualquier archivo PHP:

// no permitir acceso directo 

defined( '_JEXEC' ) or die( 'Restricted access' );

Esto evita que las personas accedan directamente a este archivo PHP.

Después de eso para indicar que está escribiendo un complemento de Contenido, agregue el siguiente código.

class plgContentNameofplugin extends JPlugin {

Tenga en cuenta el uso de letras mayúsculas. Debe reemplazar Nameofplugin por el nombre de su propio complemento.

Debe elegir ahora en qué momento se debe representar el complemento. Puede elegir entre lo siguiente:

• onContentBeforeDelete: este es un evento que se llama justo antes de que se elimine el contenido.
• onContentAfterDelete: este es un evento que se llama justo después de que se elimina el contenido.
• onContentBeforeDisplay: esta es una solicitud de información que debe colocarse inmediatamente antes del contenido generado.
• onContentAfterDisplay: esta es una solicitud de información que debe colocarse inmediatamente después del contenido generado.
• onContentBeforeSave: este es un evento que se llama justo antes de que el contenido se guarde en la base de datos.
• onContentAfterSave: este es un evento que se llama después de que el contenido se guarda en la base de datos.
• onContentAfterTitle: esta es una solicitud de información que debe colocarse entre el título del contenido y el cuerpo del contenido.
• onContentChangeState: este es un evento que se llama cuando se cambia el estado del contenido.
• onContentPrepare: esta es la primera etapa en la preparación de contenido para la salida y es el punto más común para que los complementos orientados al contenido hagan su trabajo.

Puede encontrar más información sobre qué tipo debe usar para su complemento, incluidos varios ejemplos, aquí: S: MyLanguage / Eventos de complemento / Contenido

onContentBeforeDelete

Utiliza el siguiente código:

	function  onContentBeforeDelete ( $context,  $data ) 
	{ 
		// agregue sus códigos de complemento aquí 
		return  true ; 
	}

El contexto y los datos de los parámetros deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• datos: los datos relacionados con el contenido que se va a eliminar.

onContentAfterDelete

Utiliza el siguiente código:

	function  onContentAfterDelete ( $context ,  $data ) 
	{ 
		// agregue sus códigos de complemento aquí 
		return  true ; 
	}

El contexto y los datos de los parámetros deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• datos: los datos relacionados con el contenido que se eliminó.

onContentChangeState

Utiliza el siguiente código:

	function  onContentChangeState ( $context ,  $pks ,  $value ) 
	{ 
		// agrega tus códigos de complemento aquí 
		return  true ; 
	}

Los parámetros de contexto, pks y valor deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• pks: una lista de identificadores de clave principal del contenido que ha cambiado de estado.
• valor: el valor del estado al que se ha cambiado el contenido.

onContentBeforeSave

Utiliza el siguiente código:

	function  onContentBeforeSave ( $context ,  $article ,  $isNew ) 
	{ 
		// agrega tus códigos de complemento aquí 
		return  true ; 
	}

Los parámetros context, article y isNew deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• article: objeto JTableContent que se está guardando y que contiene los datos del artículo.
• isNew: un valor booleano que se establece en verdadero si el contenido está por crearse.

onContentAfterSave

Utiliza el siguiente código:

	function  onContentAfterSave ( $context ,  $article ,  $isNew ) 
	{ 
		// agregue sus códigos de complemento aquí 
		return  true ; 
	}

Los parámetros context, article y isNew deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• article: objeto JTableContent que se guardó y que contiene los datos del artículo.
• isNew: un valor booleano que se establece en verdadero si se creó el contenido.

onContentPrepare

Utiliza el siguiente código:

	function  onContentPrepare ( $context ,  & $article ,  & $params ,  $limitstart ) 
	{ 
		// agregue sus códigos de complemento aquí 
		// sin valor de retorno 
	}

Los parámetros contexto, artículo, parámetros y limitstart deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• artículo: una referencia al artículo que está representando la vista.
• params: una referencia a una matriz asociativa de parámetros relevantes. La vista determina lo que considera relevante y transmite esa información.
• limitstart: un entero que determina la "página" del contenido que se generará. Tenga en cuenta que en el contexto de vistas que podrían no generar salida HTML, una página es un concepto razonablemente abstracto que depende del contexto.

onContentAfterTitle

Utiliza el siguiente código:

	function  onContentAfterTitle ( $context ,  & $article ,  & $params ,  $limitstart ) 
	{ 
		// agregue sus códigos de complemento aquí 
		return  '' ; 
		// devuelve un valor de cadena. El valor devuelto de este evento se mostrará en un marcador de posición. 
        // La mayoría de las plantillas muestran este marcador de posición después del separador de artículos. 
	}

Los parámetros contexto, artículo, parámetros y limitstart deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• artículo: una referencia al artículo que está representando la vista.
• params: una referencia a una matriz asociativa de parámetros relevantes. La vista determina lo que considera relevante y transmite esa información.
• limitstart: un entero que determina la "página" del contenido que se generará. Tenga en cuenta que en el contexto de vistas que podrían no generar salida HTML, una página es un concepto razonablemente abstracto que depende del contexto.

onContentBeforeDisplay

Utiliza el siguiente código:

	function  onContentBeforeDisplay ( $context ,  & $article ,  & $params ,  $limitstart ) 
	{ 
		// agregue sus códigos de complemento aquí 
		return  '' ; 
		// devuelve un valor de cadena. El valor devuelto de este evento se mostrará en un marcador de posición. 
        // La mayoría de las plantillas muestran este marcador de posición después del separador de artículos. 
	}

Los parámetros contexto, artículo, parámetros y limitstart deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• artículo: una referencia al artículo que está representando la vista.
• params: una referencia a una matriz asociativa de parámetros relevantes. La vista determina lo que considera relevante y transmite esa información.
• limitstart: un entero que determina la "página" del contenido que se generará. Tenga en cuenta que en el contexto de vistas que podrían no generar salida HTML, una página es un concepto razonablemente abstracto que depende del contexto.

onContentAfterDisplay

Utiliza el siguiente código:

	function  onContentAfterDisplay ( $context ,  & $article ,  & $params ,  $limitstart ) 
	{ 
        // agregue sus códigos de complemento aquí 
		return  '' ; 
		// devuelve un valor de cadena. El valor devuelto de este evento se mostrará en un marcador de posición. 
        // La mayoría de las plantillas muestran este marcador de posición después del separador de artículos. 
	}

Los parámetros contexto, artículo, parámetros y limitstart deben contener lo siguiente:

• context: El contexto del contenido pasado al complemento.
• artículo: una referencia al artículo que está representando la vista.
• params: una referencia a una matriz asociativa de parámetros relevantes. La vista determina lo que considera relevante y transmite esa información.
• limitstart: un entero que determina la "página" del contenido que se generará. Tenga en cuenta que en el contexto de vistas que podrían no generar salida HTML, una página es un concepto razonablemente abstracto que depende del contexto.

Archivo PHP - Ejemplo

Este ejemplo de archivo PHP trata sobre el módulo de carga del complemento de contenido de Joomla 3.1.5. Es un complemento hecho para mostrar módulos dentro de los artículos.

<?php
/**
 * @package     Joomla.Plugin
 * @subpackage  Content.loadmodule
 *
 * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

defined('_JEXEC') or die;

/**
 * Plug-in to enable loading modules into content (e.g. articles)
 * This uses the {loadmodule} syntax
 *
 * Complemento para habilitar la carga de módulos en el contenido (por ejemplo, artículos) 
 * Esto utiliza la sintaxis {loadmodule}  
 *
 * @package     Joomla.Plugin
 * @subpackage  Content.loadmodule
 * @since       1.5
 */
class PlgContentLoadmodule extends JPlugin
{
	protected static $modules = array();

	protected static $mods = array();

	/**
	 * Plugin that loads module positions within content
	 *
	 * @param   string   $context   El contexto del contenido que se pasa al complemento (plugin). 
	 * @param   object   &$article  El objeto del artículo. Nota $article->text también está disponible 
	 * @param   mixed    &$params   The article params
	 * @param   integer  $page      El número de 'página'
	 *
	 * @return  mixed   true if there is an error. Void otherwise.
         * @return   mixed  true si hay un error. Nulo de lo contrario. 
	 *
	 * @since   1.6
	 */
	public function onContentPrepare($context, &$article, &$params, $page = 0)
	{
		// Don't run this plugin when the content is being indexed
                // No ejecute este complemento cuando el contenido se indexa 
		if ($context == 'com_finder.indexer')
		{
			return true;
		}

		// Simple performance check to determine whether bot should process further
                // Verificación de rendimiento simple para determinar si el bot debe procesar más 
		if (strpos($article->text, 'loadposition') === false && strpos($article->text, 'loadmodule') === false)
		{
			return true;
		}

		// Expression to search for (positions)
		$regex		= '/{loadposition\s(.*?)}/i';
		$style		= $this->params->def('style', 'none');

		// Expression to search for(modules)
		$regexmod	= '/{loadmodule\s(.*?)}/i';
		$stylemod	= $this->params->def('style', 'none');

		// Find all instances of plugin and put in $matches for loadposition
		// $matches[0] is full pattern match, $matches[1] is the position
        // Encuentra todas las instancias del plugin y coloca $coincidencias para la posición de carga 
        // $coincidencias[0] es una coincidencia de patrón completo, $coincidencias[1] es la posición 
		preg_match_all($regex, $article->text, $matches, PREG_SET_ORDER);

		// No matches, skip this
		if ($matches)
		{
			foreach ($matches as $match)
			{
				$matcheslist = explode(',', $match[1]);

				// We may not have a module style so fall back to the plugin default.
                // Es posible que no tengamos un estilo de módulo, así que recurra al valor predeterminado del complemento. 
				if (!array_key_exists(1, $matcheslist))
				{
					$matcheslist[1] = $style;
				}

				$position = trim($matcheslist[0]);
				$style    = trim($matcheslist[1]);

				$output = $this->_load($position, $style);

				// We should replace only first occurrence in order to allow positions with the same name to regenerate their content:
                // Deberíamos reemplazar solo la primera aparición para permitir que las posiciones con el mismo nombre regeneren su contenido: 
				$article->text = preg_replace("|$match[0]|", addcslashes($output, '\\$'), $article->text, 1);
				$style = $this->params->def('style', 'none');
			}
		}

		// Find all instances of plugin and put in $matchesmod for loadmodule
		preg_match_all($regexmod, $article->text, $matchesmod, PREG_SET_ORDER);

		// If no matches, skip this
		if ($matchesmod)
		{
			foreach ($matchesmod as $matchmod)
			{
				$matchesmodlist = explode(',', $matchmod[1]);

				// We may not have a specific module so set to null
				if (!array_key_exists(1, $matchesmodlist))
				{
					$matchesmodlist[1] = null;
				}

				// We may not have a module style so fall back to the plugin default.
				if (!array_key_exists(2, $matchesmodlist))
				{
					$matchesmodlist[2] = $stylemod;
				}

				$module = trim($matchesmodlist[0]);
				$name   = htmlspecialchars_decode(trim($matchesmodlist[1]));
				$stylemod  = trim($matchesmodlist[2]);

				// $match[0] is full pattern match, $match[1] is the module,$match[2] is the title
				$output = $this->_loadmod($module, $name, $stylemod);

				// We should replace only first occurrence in order to allow positions with the same name to regenerate their content:
				$article->text = preg_replace("|$matchmod[0]|", addcslashes($output, '\\$'), $article->text, 1);
				$stylemod = $this->params->def('style', 'none');
			}
		}
	}

	/**
	 * Loads and renders the module
	 *
	 * @param   string  $position  The position assigned to the module
	 * @param   string  $style     The style assigned to the module
	 *
	 * @return  mixed
	 *
	 * @since   1.6
	 */
	protected function _load($position, $style = 'none')
	{
		self::$modules[$position] = '';
		$document	= JFactory::getDocument();
		$renderer	= $document->loadRenderer('module');
		$modules	= JModuleHelper::getModules($position);
		$params		= array('style' => $style);
		ob_start();

		foreach ($modules as $module)
		{
			echo $renderer->render($module, $params);
		}

		self::$modules[$position] = ob_get_clean();

		return self::$modules[$position];
	}

	/**
	 * This is always going to get the first instance of the module type unless
	 * there is a title.
	 *
	 * @param   string  $module  The module title
	 * @param   string  $title   The title of the module
	 * @param   string  $style   The style of the module
	 *
	 * @return  mixed
	 *
	 * @since   1.6
	 */
	protected function _loadmod($module, $title, $style = 'none')
	{
		self::$mods[$module] = '';
		$document	= JFactory::getDocument();
		$renderer	= $document->loadRenderer('module');
		$mod		= JModuleHelper::getModule($module, $title);

		// If the module without the mod_ isn't found, try it with mod_.
		// This allows people to enter it either way in the content
		if (!isset($mod))
		{
			$name = 'mod_'.$module;
			$mod  = JModuleHelper::getModule($name, $title);
		}

		$params = array('style' => $style);
		ob_start();

		echo $renderer->render($mod, $params);

		self::$mods[$module] = ob_get_clean();

		return self::$mods[$module];
	}
}

Archivo (s) INI

Para la internacionalización es bueno usar los archivos INI. Puede agregar al archivo de idioma todo lo que envía texto al usuario, en este orden:

• Etiqueta de descripción XML
• Etiqueta XML y atributos de descripción de parámetros
• JText::_( 'string' ) utilizado por el complemento

Debe crear dos archivos: uno para el backend y otro para el front-end. El nombre debe coincidir con la ruta de la extensión. Por ejemplo, si estábamos creando un complemento de contenido llamado 'ejemplo' y se instala en plugins / content / example, entonces nuestros archivos deberían llamarse:

• es-GB.plg_content_example.ini (Frontend)
• es-GB.plg_content_example.sys.ini (Backend)

Comience su archivo INI con algo como esto:

; $ Id: en-GB.plg_content_nameofplugin.ini 
; Joomla! Proyecto 
; Copyright (C) 2005 - 2007 Asuntos de código abierto. Todos los derechos reservados. 
; Licencia http://www.gnu.org/licenses/gpl-2.0.html GNU / GPL, ver LICENCIA.php 
; Nota: Todos los archivos ini deben guardarse como UTF-8 - Sin BOM

Por supuesto, también puede agregar otra información, como el autor.

Ejemplo de backend:

<field  name = "modo"  type = "lista"  default = "1"  label = "PLG_CONTENT_EXAMPLE_MODE"  Description = "PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED" > 
   <option  value = "0" > PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT </ option> 
   <option  value = "1" > PLG_CONTENT_EXAMPLE_LINKABLE_TEXT </option> 
</field>

Las cadenas localizadas se traducen en el archivo ini:

PLG_CONTENT_EXAMPLE_MODE = Modo 
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED = Seleccione cómo se mostrarán los correos electrónicos 
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT = Texto 
no enlazable PLG_CONTENT_EXAMPLE_LINKABLE_TEXT = Como direccionar enlazable

La mejor práctica dicta que LOCALIZED_TAGS son todas mayúsculas, sin espacios, y comienzan con el mismo nombre que la extensión, para evitar interferir con otras cadenas.

Las etiquetas localizadas se pueden traducir a varios idiomas. Cuando desee que su complemento de contenido esté disponible en más idiomas, primero agréguelos a la etiqueta <languages> en el archivo XML. Luego cree el mismo archivo INI y cambie la parte después de =, por ejemplo, la versión holandesa sería:

PLG_CONTENT_EXAMPLE_MODE=Modus
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED=Selecteer hoe de e-mails worden weergegeven
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT=Niet-linkbare tekst
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT=Als een linkbaar mailto adres

Ejemplo frontend:

PLG_CONTENT_EXAMPLE_LINKNAME = "¡El nombre del enlace va aquí!"

En el archivo php del complemento, debe cargar el archivo de idioma, sin embargo, a diferencia de Joomla 1.5, ahora podemos hacer esto anulando el constructor, con una función proporcionada por Joomla en JPlugin.

function __construct(& $subject, $config)
{
	$this->loadLanguage();
	parent::__construct($subject, $config);
}

También puede usar otro componente o el archivo de idioma del complemento. Esto es útil para mantener cadenas consistentes entre un componente, módulo y complemento, que forman parte del mismo paquete.

Para cargar los archivos de idioma de otro componente o complemento, especifique su nombre en la declaración de carga y especifique si usar el sitio o el idioma del administrador. Por ejemplo:

$lang->load('com_someothercomponent', JPATH_ADMINISTRATOR);

Ejemplos de codificación

Hay siete Joomla! Complementos de contenido principal. Para aprender a escribir buenos complementos, es bueno mirar en los archivos de Joomla! 2.5 o 3.x Puede verlos 'funcionando' cuando va al Back-end de su Joomla! instalación, luego vaya al menú 'Extensiones' y seleccione el 'Administrador de complementos'. Haga clic en el nombre del complemento para editarlo; y verlo funcionando. También mire el contenido y vea qué sucede cuando inserta un salto de página, por ejemplo.

Consejos rápidos

• En el archivo PHP, a menudo olvida colocar un punto y coma (;) al final de una fila, lo que causa errores. Verifique esto antes de probar su complemento y eliminará muchos errores.
• Tenga en cuenta el hecho de que los parámetros en el archivo XML están cerrados correctamente. Cuando agrega opciones, por ejemplo, debe cerrarlo con </field>.
• Es fácil probar en un host local cuando todavía está ocupado editando su complemento.
• Un zip típico contendrá lo siguiente:
  • nameofplugin.xml
  • nameofplugin.php
  • es-GB.plg_content_nameofplugin.ini