Crear Extensiones para FacturaScripts

Amplía funcionalidades existentes sin modificar el código base

¿Qué son las Extensiones?

Las extensiones permiten modificar y ampliar el comportamiento de FacturaScripts sin alterar los archivos core del sistema. Son ideales para añadir campos personalizados, modificar vistas o extender funcionalidades.

🎯 Ventajas de las Extensiones

  • No modifican código core
  • Compatibles con actualizaciones
  • Fáciles de mantener
  • Reutilizables
  • Seguras y estables

📦 Ejemplo: ModCliente

  • Función: Añadir campo "Capital Social"
  • Método: Extensión del modelo Cliente
  • Archivos: 5 componentes esenciales
  • Compatibilidad: FacturaScripts 2025+

Estructura de una Extensión

Una extensión básica requiere estos archivos organizados en una estructura específica:

Plugins/
└── ModCliente/
    ├── Extension/
    │   └── Table/
    │       └── cliente.xml
    │   └── XMLView/
    │       ├── EditCliente.xml
    │       └── ListCliente.xml
    ├── Init.php
    └── facturascripts.ini

Paso 1: Configuración del Plugin (facturascripts.ini)

Define la información básica de la extensión:

[plugin]
name = ModCliente
description = Mod expansión de plugin
version = 0.1
min_version = 2025

💡 Nota importante

Para extensiones, el min_version debe coincidir con la versión de FacturaScripts que estés usando para garantizar compatibilidad.

Paso 2: Archivo de Inicialización (Init.php)

Este archivo gestiona el ciclo de vida de la extensión:

<?php

namespace FacturaScripts\Plugins\ModCliente;

use FacturaScripts\Core\Template\InitClass;

class Init extends InitClass
{
    public function init(): void
    {
        $this->loadExtension(new Extension\Controller\ListCliente());
    }

    public function uninstall(): void
    {
        // Limpieza de datos o configuraciones al desinstalar el plugin
    }

    public function update(): void
    {
        // Ajustes al instalar o actualizar el plugin
    }
}

🔧 Funciones principales

  • init(): Carga las extensiones al activar el plugin
  • uninstall(): Limpieza al desinstalar
  • update(): Migraciones entre versiones

Paso 3: Extensión del Controlador

Crea la clase que extiende el comportamiento del controlador original:

<?php

namespace FacturaScripts\Plugins\ModCliente\Extension\Controller;

use FacturaScripts\Core\Base\Extension;

class ListCliente extends Extension
{
    public function run(): void
    {
        // Aquí puedes modificar el comportamiento del controlador ListCliente
        // Por ejemplo, añadir filtros personalizados, modificar datos, etc.
    }
}

Ubicación: Extension/Controller/ListCliente.php

Paso 4: Extender el Modelo (cliente.xml)

Añade nuevos campos a la tabla existente mediante XML:

<?xml version="1.0" encoding="UTF-8"?>
<table>
    <column>
        <name>capitalsocial</name>
        <type>Integer</type>
        <default></default>
    </column>
</table>

📋 Tipos de datos disponibles

  • Integer: Números enteros
  • Double: Números decimales
  • Varchar: Texto corto (especificar length)
  • Text: Texto largo
  • Boolean: Verdadero/Falso
  • Date/DateTime: Fechas

Paso 5: Vista de Listado (ListCliente.xml)

Define cómo se muestra el nuevo campo en la lista de clientes:

<?xml version="1.0" encoding="UTF-8"?>
<view>
    <columns>
           <column name="Capital social" order="189">
              <widget type="money" fieldname="capitalsocial" />
           </column>
    </columns>
</view>

🎨 Tipos de Widget disponibles

  • text: Campo de texto simple
  • money: Campo monetario con formato
  • number: Campo numérico
  • checkbox: Casilla de verificación
  • date: Selector de fecha
  • select: Lista desplegable

Paso 6: Vista de Edición (EditCliente.xml)

Define cómo se edita el nuevo campo en el formulario de cliente:

<?xml version="1.0" encoding="UTF-8"?>
<view>
    <columns>
        <group name="contact" title="contact-info" numcolumns="12">
           <column name="Capital social">
              <widget type="money" fieldname="capitalsocial" />
           </column>
        </group>
    </columns>
</view>

📐 Organización en grupos

Los grupos permiten organizar los campos en secciones lógicas. El atributo numcolumns define el ancho en el sistema de grid (1-12).

Flujo de Instalación

1. Crear la estructura de directorios

Crea la carpeta Plugins/ModCliente/ con todos los subdirectorios necesarios.

2. Copiar los archivos

Coloca cada archivo en su ubicación correspondiente según la estructura mostrada.

3. Activar el plugin

  1. Ve a "Administración → Plugins"
  2. Busca "ModCliente" en la lista
  3. Haz clic en "Activar"
  4. FacturaScripts creará automáticamente la columna en la base de datos

4. Verificar la instalación

  • Navega a "Clientes → Clientes"
  • Verifica que aparezca la columna "Capital social"
  • Edita un cliente y comprueba que el campo esté disponible

Ejemplo Avanzado: Extensión Completa

Vamos a crear una extensión más compleja que añade múltiples campos y funcionalidades:

Modelo extendido (cliente.xml)

<?xml version="1.0" encoding="UTF-8"?>
<table>
    <column>
        <name>capitalsocial</name>
        <type>Integer</type>
        <default>0</default>
    </column>
    <column>
        <name>fechaconstitucion</name>
        <type>Date</type>
        <default></default>
    </column>
    <column>
        <name>esempresa</name>
        <type>Boolean</type>
        <default>false</default>
    </column>
    <column>
        <name>notasinternas</name>
        <type>Text</type>
        <default></default>
    </column>
</table>

Controlador extendido (ListCliente.php)

<?php

namespace FacturaScripts\Plugins\ModCliente\Extension\Controller;

use FacturaScripts\Core\Base\Extension;

class ListCliente extends Extension
{
    public function run(): void
    {
        // Añadir filtro personalizado para empresas
        $this->getController()->addFilterSelect('esempresa', 'Tipo', [
            '' => 'Todos',
            'true' => 'Solo empresas',
            'false' => 'Solo personas'
        ]);
        
        // Modificar la consulta base
        $this->getController()->addSearchFields(['notasinternas']);
    }
    
    public function beforeRender(): void
    {
        // Modificaciones antes de renderizar la vista
        $view = $this->getController()->getView('ListCliente');
        if ($view) {
            // Personalizar la vista
        }
    }
}

Solución de Problemas Comunes

Campo no aparece

  • Verifica que el plugin esté activado
  • Comprueba los nombres de los campos en los XML
  • Revisa los logs en MyFiles/Logs/
  • Forza recarga con Ctrl+F5

Errores de base de datos

  • Verifica la sintaxis XML del modelo
  • Comprueba que el tipo de dato sea válido
  • Revisa que no existan conflictos de nombres
  • Desactiva y reactiva el plugin

Extension no se carga

  • Verifica el namespace en Init.php
  • Comprueba la ruta de la extensión
  • Revisa que la clase extienda correctamente
  • Confirma que el método loadExtension se llame

Mejores Prácticas para Extensiones

📁 Estructura y naming

  • Usa prefijos "Mod" para extensiones
  • Mantén nombres descriptivos
  • Organiza los archivos por funcionalidad
  • Documenta tus cambios

🔧 Desarrollo

  • Testea en entorno de desarrollo
  • Maneja errores gracefulmente
  • Respeta el flujo existente
  • Usa tipos de datos apropiados

🚀 Rendimiento

  • Evita extensiones muy pesadas
  • Optimiza consultas de base de datos
  • Usa caché cuando sea apropiado
  • Minimiza hooks costosos

Próximos Pasos y Recursos

🚀 Funcionalidades Avanzadas

  • Crear hooks personalizados
  • Extender múltiples controladores
  • Añadir validaciones custom
  • Integrar con APIs externas

📚 Recursos Adicionales

🛠️ Herramientas Útiles

  • XML validator para los archivos de modelo
  • PHP Code Sniffer para estándares de código
  • Database manager para ver cambios
  • Browser DevTools para debugging

Conclusión

Las extensiones son una herramienta poderosa para personalizar FacturaScripts sin comprometer la actualizabilidad del sistema. Siguiendo esta guía, puedes añadir funcionalidades específicas a tu negocio manteniendo la estabilidad y compatibilidad con versiones futuras.

✅ ¡Ya estás listo para crear tus propias extensiones!

Comienza con extensiones simples y gradualmente avanza hacia funcionalidades más complejas. Recuerda siempre testear en un entorno de desarrollo antes de implementar en producción.