Estructura de los complementos 

En versiones previas de XF, existen muy pocos estándares y convenciones que aborden el desarrollo de complementos. Hemos realizado varios cambios en XF 2.0. Así son algunos de estos cambios:

IDs y rutas de los complementos

Cada complemento instalado debe tener un único ID y éste ID dicta cuando un complemento puede almacenar sus archivos en el sistema de archivos. Existen dos posibles formatos para los ID de complemento.

El primer tipo "simple" debe ser una sola palabra que no contenga ningún caracter especial. Por ejemplo, Demo.

Los IDs de complemento deben seguir las siguientes reglas:

• Sólo puede contener a-z o A-Z
• Puede contener 0-9 pero nunca al inicio del ID
• No puede contener caracteres especiales como barras, guiones o subrayados

La segunda contiene un prefijo de vendedor, por lo que si fabricas complementos para una compañía o con marca, el ID del complemento indicará esto. Por ejemplo, XenFacil/Demo.

El Id de complemento del tipo vendedor debe seguir las siguientes reglas:

• Solo puede contener caracteres a-z o A-Z
• Puede contener un caracter / sinple pero nunca al comienzo o final.
• Puede contener 0-9 pero nunca al comienzo de alguna de las partes del ID de complemento

Una vez decidido cómo va a ser el ID del complemento, sabremos con total conocimiento donde están almacenados sus archivos. Todos los complementos para XF 2.0 están almacenados en un subdirectorio del directorio src/addons.

Si tienes un simple ID de complemento, ej. Demo, sus archivos se almacenarán en la siguiente localización: src/addons/Demo.

Si tienes un ID de complemento basado en un vendedor, ej. XenFacil/Demo, sus archivos estarán ubicados en: src/addons/XenFacil/Demo.

El ID de complemento elegido también ofrece el prefijo de clase de nombre de espacio (véase Nombres de espacio para una mayor información).

Formato recomendado de versión

XF, por sí mismo, usa un principio MAJOR.MINOR.PATCH (ej. 2.0.0 para el primer lanzamiento estable de XF2) en sus números de versión y recomendamos que se adopte un enfoque similar con respecto a la versión de tus propios complementos. En términos básicos, incrementar la

• versión MAJOR cuando se realicen cambios mayores en sus características, especialmente cambios que rompan la compatibilidad hacia atrás
• versión MINOR cuando se añade funcionalidad preferiblemente de un modo compatible hacia atrás, y
• versión PATCH cuando se hacen correcciones de errores compatibles con versiones anteriores

Formato de ID recomendado de versión

Los IDs de versión de complementos son enteros básicos que se usan para comparaciones internas de versiones. Nos permiten detectar más fácilmente cuando una versión es más antigua que otra. Cada versión del complemento debe incrementar este ID en, al menos, 1, pero por convención interna de XF, es potentialmente más útil también para los complementos. Nuestros IDs de versión están en el formato aabbccde.

• aa representa el número de versión mayor
• bb representa el número de versión menor
• cc representa la versión de ruta
• d representa el estado, ej. 1 para lanzamientos alfa, 3 para lanzamientos beta, 5 para candidatos al lanzamiento y 7 para lanzamientos estables.
• e representa el estado de la versión

Por ejemplo, un complemento con versión 1.7.3 candidato al lanzamiento 4 debe tener un ID 1070354. El lanzamiento de la versión final estable de XF2 tendrá un ID 2000070. La versión 1.5.0 Beta 3 de XF tiene un ID1050033. La versión estable 99.99.99 tendrá un ID 99999970 ... y tal vez se debiera ir más despacio

Archivos y directorios comunes de complementos

Existe un número de archivos y directorios en el interior del directorio de complementos que tienen un propósito y significado especiales.

Archivo addon.json

addon.json es un archivo que contiene un número de partes de información que se requieren para ayudar a XF 2.0 a identificar el complemento y mostrar esa información en el Panel de control de administración. Por lo menos, el archivo addon.json debe lucir algo así:

{"title":"Mi complemento de la compañía XenFacil", "version_string":"2.0.0", "version_id":2000070}
                
                

Se deberá crearse un archivo básico cuando se crea un complemento. Soporta mucho más, además del ejemplo anterior aunque entraremos en ello con más detalle más tarde.

Incluir este archivo es obligatorio.

Archivo hashes.json

hashes.json es el nuevo método para agregar soporte al Sistema de comprobación de salud de archivos, y la mejor parte es -- ¡que se genera automáticamente!

Como parte de la exportación del complemento y proceso de generación (más, más tarde) podremos hacer un rápido inventario de todos nuestros archivos de complemento y escribir parte del contenido de los archivos.

Incluir este archivo es obligatorio y la instalación del complemento se bloqueará sin él.

Archivo setup.php

Setup.php

Veremos más detalles sobre cómo crear una clase setup más abajo.

Directorio _data

El directorio _data es donde se almacenan los datos maestros del complemento. Cada tipo de dato del complemento tiene su própio archivo XML (en vez de un solo tipo para todos los tipos). Las partes de estos archivos se incluirán dentro del archivo hashes.json por lo que hay que asegurarse de que el complemento está completo y con datos consistentes antes de permitir la instalación de un complemento.

Directorio _output

El directoriob _output no se precisa para tener una instalación con éxito de un complemento y no debe incluirse al lanzar el complemento. Púramente, este directorio es para propósitos de desarrollo y solo se usa si el modo de desarrollo está activado (Activar el modo de desarrollo).

Cada elemento de los datos del complemento se almacena en un archivo separado. En su mayoría se almacenan como archivos JSON, pero en el caso de las frases se almacenan como archivos TXT y las plantillas se almacenan como archivos HTML/CSS/LESS. Todos los tipos de plantillas son editables directamente en el sistema de archivos y los cambios realizados en estos archivos se devuelven automáticamente a la base de datos en su carga.

Clase setup

Para crear una clase Setup (clase de instalación) para el complemento, todo lo que se necesita es crear un archivo denominado Setup.php en la raíz del directorio del complemento.

La clase Setup puede extenderse \XF\AddOn\AbstractSetup como se requiera, cómo mínimo, para implementar los métodos install(), upgrade() y uninstall(). La clase Setup del complemento se parece a algo como esto:

<?php

namespace Demo;

class Setup extends\XF\AddOn\AbstractSetup
{
    public function install(array$stepParams= [])
    {
        $this->db()->query(" CREATE TABLE xf_demo ( demo_id INT(11) UNSIGNED NOT NULL ) ");
    }
    public function upgrade(array$stepParams= [])
    {
        if ($this->addOn->version_id < 1000170)
        {
            $this->db()->query(" ALTER TABLE xf_demo ADD foo VARCHAR(10) NOT NULL DEFAULT '' "); 
        } 
    }
    public  functionuninstall(array$stepParams= [])
    {
        $this->db()->query(" DROP TABLE xf_demo ");
}
                

La clase Setup también soporta ejecutar cada una de las acciones en diferentes pasos. Para implementar este comportamiento la clase puede usar los rasgos StepRunnerInstallTrait, StepRunnerUpgradeTrait y/o StepRunnerUninstallTrait. Estos implementan automáticamente los métodos requeridos, y solo se necesita agregar los pasos relevantes, ej. installStep1(), upgrade1000170Step(), upgrade1000170Step1() y uninstallStep1(), donde 1000170, etc. de los métodos de actualización son los IDs de versión del complemento (véase Formato de ID recomendado de versión).