Cómo gestionar las rutas en Joomla para cargar assets de media durante el desarrollo

Hace poco comenzamos a actualizar una plantilla antigua de Joomla 3 a Joomla 5. Desde Joomla 4.0 se recomienda que, en producción, las plantillas finales guarden sus recursos como CSS, JavaScript e imágenes dentro del directorio media. Esto ayuda a que Joomla sea más rápido y a que la instalación esté más organizada.

El resto de archivos —index.php (la estructura base), overrides de componentes, plugins y módulos— se mantienen en templates/nombrePlantilla.

El problema que nos surgió fue el siguiente:

¿Cómo trabajar en desarrollo con todos los recursos juntos y luego generar una plantilla lista para publicar siguiendo las buenas prácticas de Joomla?

En este artículo te voy a contar cómo Joomla gestiona la instalación de plantillas, cómo usar templateDetails.xml y joomla.asset.json para tener un flujo de trabajo limpio y versionable y cómo pasar fácilmente de desarrollo a producción sin romper rutas.

Un flujo de trabajo cómodo: todo junto en desarrollo, separado en producción

Durante el desarrollo de una plantilla Joomla es más cómodo tener todos los archivos en una sola carpeta. La clave está en que, al empaquetar la plantilla para producción:

• Los archivos PHP, overrides y estructura base deben ir a templates/nombrePlantilla
• Los recursos estáticos (CSS, JS, imágenes) deben ir a media/templates/site/nombrePlantilla

Para esto Joomla nos da dos herramientas clave: templateDetails.xml y joomla.asset.json.

templateDetails.xml: organizando la instalación de la plantilla

El archivo templateDetails.xml es fundamental. Aquí le indicamos a Joomla qué archivos instalar, dónde colocarlos y cómo manejar la plantilla desde el administrador.

<files> – Archivos de la carpeta de la plantilla

En esta sección definimos los ficheros que van directamente a la carpeta principal de la plantilla. Ejemplo (de Cassiopeia):

<files>
    <filename>component.php</filename>
    <filename>error.php</filename>
    <filename>index.php</filename>
    <filename>joomla.asset.json</filename>
    <filename>offline.php</filename>
    <filename>templateDetails.xml</filename>
    <folder>html</folder>
</files>

<media> – Recursos que irán al directorio media

Aquí definimos qué carpetas del paquete se instalarán en el directorio media de Joomla. Esto es lo que nos permite separar los assets de la lógica de la plantilla.

Ejemplo:

<media destination="templates/site/cassiopeia" folder="media">
    <folder>js</folder>
    <folder>css</folder>
    <folder>scss</folder>
    <folder>images</folder>
</media>

Con esto, al instalar la plantilla, Joomla colocará esos archivos en: media/templates/site/cassiopeia/

¿Cómo decide Joomla de dónde cargar los assets?

Aquí entra en juego joomla.asset.json, un archivo que Joomla usa desde la versión 4.0 para gestionar la carga de recursos. Este archivo nos permite declarar cada asset, asignarle un nombre único y establecer su ruta, evitando tener que tocar el index.php.

Ejemplo:

{
    "name": "tpl_svbasic.bootstrap",
    "type": "style",
    "uri": "templates/solucionesvigobasicresponsiveJ5/css/bootstrap.min.css"
}

• name → nombre único del recurso.
• type → tipo de recurso (style para CSS, script para JS, etc.).
• uri → ruta desde la raíz de Joomla.

Cargando un asset en Joomla

Si tenemos el recurso definido en joomla.asset.json, lo podemos cargar así:

use Joomla\CMS\Factory;

$app = Factory::getApplication();
$doc = $app->getDocument();

$wa = $doc->getWebAssetManager();
$wa->useStyle('tpl_svbasic.bootstrap');

O incluso registrarlo y usarlo directamente:

$wa->registerAndUseStyle(
    'tpl_svbasic.bootstrap',
    'templates/solucionesvigobasicresponsiveJ5/css/bootstrap.min.css'
);

Estrategia para desarrollo y producción

En desarrollo, trabajamos con las rutas dentro de la carpeta templates:

{
    "name": "tpl_svbasic.bootstrap",
    "type": "style",
    "uri": "templates/solucionesvigobasicresponsiveJ5/css/bootstrap.min.css"
}

En producción, cambiamos la ruta para que apunte al directorio media:

{
    "name": "tpl_svbasic.bootstrap",
    "type": "style",
    "uri": "media/templates/site/solucionesvigobasicresponsiveJ5/css/bootstrap.min.css"
}

Así conseguimos:

1. Tener todos los recursos juntos y fácilmente versionables durante el desarrollo.
2. Cambiar solo la ruta al empaquetar la plantilla.
3. Hacer que Joomla coloque automáticamente cada archivo en su sitio durante la instalación.

Ventajas de este método

• Entorno de trabajo limpio y controlado.
• Cumple con las recomendaciones oficiales para plantillas Joomla 4 y Joomla 5.
• Evita rutas rotas y búsquedas interminables en el código.

Si desarrollas plantillas Joomla, este flujo de trabajo es una de las formas más cómodas y seguras de gestionar las rutas y cargar assets desde media, sin perder el control durante el desarrollo y sin complicaciones al publicar.