Referencia de API de XoopsModule

Documentación completa de API para el sistema de módulos de XOOPS.

---

Arquitectura del Sistema de Módulos

graph TB
    subgraph "Module Loading"
        A[Request] --> B[Router]
        B --> C{Module Exists?}
        C -->|Yes| D[Load xoops_version.php]
        C -->|No| E[404 Error]
        D --> F[Initialize Module]
        F --> G[Check Permissions]
        G --> H[Execute Controller]
    end

    subgraph "Module Components"
        I[XoopsModule] --> J[Config]
        I --> K[Templates]
        I --> L[Blocks]
        I --> M[Handlers]
        I --> N[Preloads]
    end

    H --> I

---

Clase XoopsModule

Definición de Clase

class XoopsModule extends XoopsObject
{
    // Propiedades
    public $modinfo;      // Array de información del módulo
    public $adminmenu;    // Elementos del menú de administración

    // Métodos
    public function __construct();
    public function loadInfo(string $dirname, bool $verbose = true): bool;
    public function getInfo(string $name = null): mixed;
    public function setInfo(string $name, mixed $value): bool;
    public function mainLink(): string;
    public function subLink(): string;
    public function loadAdminMenu(): void;
    public function getAdminMenu(): array;
    public function loadConfig(): bool;
    public function getConfig(string $name = null): mixed;
}

Propiedades

Propiedad	Tipo	Descripción
mid	int	ID del módulo
name	string	Nombre de visualización
version	string	Número de versión
dirname	string	Nombre del directorio
isactive	int	Estado activo (0/1)
hasmain	int	Tiene área principal
hasadmin	int	Tiene área de administración
hassearch	int	Tiene función de búsqueda
hasconfig	int	Tiene configuración
hascomments	int	Tiene comentarios
hasnotification	int	Tiene notificaciones

Métodos Principales

// Obtener instancia del módulo
$module = $GLOBALS['xoopsModule'];

// O cargar por dirname
$moduleHandler = xoops_getHandler('module');
$module = $moduleHandler->getByDirname('mymodule');

// Obtener información del módulo
$version = $module->getVar('version');
$name = $module->getVar('name');
$dirname = $module->getVar('dirname');

// Obtener configuración del módulo
$config = $module->getConfig();
$specificConfig = $module->getConfig('items_per_page');

// Verificar si el módulo tiene función
$hasAdmin = $module->getVar('hasadmin');
$hasSearch = $module->getVar('hassearch');

// Obtener ruta del módulo
$modulePath = XOOPS_ROOT_PATH . '/modules/' . $module->getVar('dirname');
$moduleUrl = XOOPS_URL . '/modules/' . $module->getVar('dirname');

---

XoopsModuleHandler

Definición de Clase

class XoopsModuleHandler extends XoopsPersistableObjectHandler
{
    public function create(bool $isNew = true): XoopsModule;
    public function get(int $id): ?XoopsModule;
    public function getByDirname(string $dirname): ?XoopsModule;
    public function insert(XoopsObject $module, bool $force = false): bool;
    public function delete(XoopsObject $module, bool $force = false): bool;
    public function getList(?CriteriaElement $criteria = null): array;
    public function getObjects(?CriteriaElement $criteria = null): array;
}

Ejemplos de Uso

// Obtener manejador
$moduleHandler = xoops_getHandler('module');

// Obtener todos los módulos activos
$criteria = new Criteria('isactive', 1);
$activeModules = $moduleHandler->getObjects($criteria);

// Obtener módulo por dirname
$publisherModule = $moduleHandler->getByDirname('publisher');

// Obtener módulos con administración
$criteria = new CriteriaCompo();
$criteria->add(new Criteria('isactive', 1));
$criteria->add(new Criteria('hasadmin', 1));
$adminModules = $moduleHandler->getObjects($criteria);

// Verificar si el módulo está instalado
$module = $moduleHandler->getByDirname('mymodule');
if ($module && $module->getVar('isactive')) {
    // El módulo está instalado y activo
}

---

Ciclo de Vida del Módulo

stateDiagram-v2
    [*] --> Desinstalado

    Desinstalado --> Instalando: Instalar Módulo
    Instalando --> Instalado: Éxito
    Instalando --> Desinstalado: Error

    Instalado --> Activo: Activar
    Instalado --> Desinstalando: Desinstalar

    Activo --> Inactivo: Desactivar
    Activo --> Actualizando: Actualización Disponible

    Inactivo --> Activo: Activar
    Inactivo --> Desinstalando: Desinstalar

    Actualizando --> Activo: Éxito en Actualización
    Actualizando --> Activo: Error en Actualización

    Desinstalando --> Desinstalado: Éxito
    Desinstalando --> Instalado: Error

    Desinstalado --> [*]

---

Estructura de xoops_version.php

<?php
// Metadatos del módulo
$modversion['name']        = _MI_MYMODULE_NAME;
$modversion['version']     = '1.0.0';
$modversion['description'] = _MI_MYMODULE_DESC;
$modversion['author']      = 'Tu Nombre';
$modversion['credits']     = 'Comunidad XOOPS';
$modversion['license']     = 'GPL 2.0+';
$modversion['license_url'] = 'https://www.gnu.org/licenses/gpl-2.0.html';
$modversion['image']       = 'assets/images/logo.png';
$modversion['dirname']     = basename(__DIR__);

// Requisitos
$modversion['min_php']     = '7.4';
$modversion['min_xoops']   = '2.5.10';
$modversion['min_admin']   = '1.2';
$modversion['min_db']      = ['mysql' => '5.7', 'mysqli' => '5.7'];

// Funcionalidades
$modversion['hasMain']     = 1;
$modversion['hasAdmin']    = 1;
$modversion['hasSearch']   = 1;
$modversion['hasComments'] = 1;
$modversion['hasNotification'] = 1;

// Menú de Administración
$modversion['adminindex']  = 'admin/index.php';
$modversion['adminmenu']   = 'admin/menu.php';

// Tablas de base de datos
$modversion['sqlfile']['mysql'] = 'sql/mysql.sql';
$modversion['tables'] = [
    $modversion['dirname'] . '_items',
    $modversion['dirname'] . '_categories',
];

// Plantillas
$modversion['templates'] = [
    ['file' => 'mymodule_index.tpl', 'description' => 'Plantilla de índice'],
    ['file' => 'mymodule_item.tpl', 'description' => 'Plantilla de elemento'],
];

// Bloques
$modversion['blocks'][] = [
    'file'        => 'blocks/recent.php',
    'name'        => _MI_MYMODULE_BLOCK_RECENT,
    'description' => _MI_MYMODULE_BLOCK_RECENT_DESC,
    'show_func'   => 'mymodule_block_recent_show',
    'edit_func'   => 'mymodule_block_recent_edit',
    'options'     => '10|0',
    'template'    => 'mymodule_block_recent.tpl',
];

// Opciones de configuración
$modversion['config'][] = [
    'name'        => 'items_per_page',
    'title'       => '_MI_MYMODULE_ITEMS_PER_PAGE',
    'description' => '_MI_MYMODULE_ITEMS_PER_PAGE_DESC',
    'formtype'    => 'textbox',
    'valuetype'   => 'int',
    'default'     => 10,
];

// Búsqueda
$modversion['search'] = [
    'file' => 'include/search.inc.php',
    'func' => 'mymodule_search',
];

// Comentarios
$modversion['comments'] = [
    'itemName' => 'item_id',
    'pageName' => 'item.php',
    'callbackFile' => 'include/comment_functions.php',
    'callback' => [
        'approve' => 'mymodule_comment_approve',
        'update'  => 'mymodule_comment_update',
    ],
];

// Notificaciones
$modversion['notification'] = [
    'lookup_file' => 'include/notification.inc.php',
    'lookup_func' => 'mymodule_notify_iteminfo',
    'category' => [
        [
            'name'           => 'global',
            'title'          => _MI_MYMODULE_NOTIFY_GLOBAL,
            'description'    => _MI_MYMODULE_NOTIFY_GLOBAL_DESC,
            'subscribe_from' => ['index.php'],
        ],
        [
            'name'           => 'item',
            'title'          => _MI_MYMODULE_NOTIFY_ITEM,
            'description'    => _MI_MYMODULE_NOTIFY_ITEM_DESC,
            'subscribe_from' => ['item.php'],
            'item_name'      => 'item_id',
            'allow_bookmark' => 1,
        ],
    ],
    'event' => [
        [
            'name'          => 'new_item',
            'category'      => 'global',
            'title'         => _MI_MYMODULE_NOTIFY_NEW_ITEM,
            'caption'       => _MI_MYMODULE_NOTIFY_NEW_ITEM_CAP,
            'description'   => _MI_MYMODULE_NOTIFY_NEW_ITEM_DESC,
            'mail_template' => 'notify_newitem',
            'mail_subject'  => _MI_MYMODULE_NOTIFY_NEW_ITEM_SBJ,
        ],
    ],
];

---

Patrón Auxiliar del Módulo

<?php
namespace XoopsModules\MyModule;

class Helper extends \Xmf\Module\Helper
{
    public function __construct()
    {
        $this->dirname = basename(dirname(__DIR__));
    }

    public static function getInstance(): self
    {
        static $instance = null;
        if ($instance === null) {
            $instance = new self();
        }
        return $instance;
    }

    public function getHandler(string $name): ?object
    {
        return $this->getHandlerByName($name);
    }

    public function getConfig(string $name = null)
    {
        return parent::getConfig($name);
    }
}

// Uso
$helper = Helper::getInstance();
$itemHandler = $helper->getHandler('Item');
$perPage = $helper->getConfig('items_per_page');

---

Flujo de Instalación del Módulo

sequenceDiagram
    participant Admin
    participant System
    participant Database
    participant FileSystem

    Admin->>System: Instalar Módulo
    System->>FileSystem: Leer xoops_version.php
    FileSystem-->>System: Configuración del Módulo

    System->>Database: Crear tablas (mysql.sql)
    Database-->>System: Tablas creadas

    System->>Database: Insertar registro del módulo
    System->>Database: Insertar opciones de configuración
    System->>Database: Insertar plantillas
    System->>Database: Insertar bloques

    System->>FileSystem: Compilar plantillas
    FileSystem-->>System: Plantillas compiladas

    System->>Database: Establecer módulo activo
    System-->>Admin: Instalación completa

---

Documentación Relacionada

• API XoopsObject
• Guía de Desarrollo de Módulos
• Arquitectura XOOPS

---

#xoops #api #module #xoopsmodule #reference