Gestión de Dependencias de Snippets

Elemental CMS proporciona un sistema integral de gestión de dependencias para snippets, permitiéndote incluir recursos CSS y JavaScript que se cargan automáticamente cuando los snippets se renderizan. Esta guía explica cómo funcionan las dependencias y cómo gestionarlas efectivamente.

Entendiendo las Dependencias de Snippets

Los snippets pueden tener dos tipos de dependencias:

Dependencias CSS: Hojas de estilo que definen la apariencia visual
Dependencias JavaScript: Scripts que proporcionan funcionalidad interactiva

Estas dependencias se almacenan en la especificación del snippet y se inyectan automáticamente cuando el snippet se renderiza.

Estructura de Dependencias de Snippets

Cada snippet tiene un archivo de especificación (`.json`) que incluye arrays de dependencias:

{
    "_id": ObjectId("..."),
    "name": "nav-bar",
    "cssDeps": [
        {
            "name": "bootstrap",
            "type": "text/css",
            "url": "css/bootstrap.min.css",
            "meta": {
                "integrity": "sha384-...",
                "crossorigin": "anonymous"
            }
        }
    ],
    "jsDeps": [
        {
            "name": "jquery",
            "type": "application/javascript",
            "url": "js/jquery.min.js",
            "meta": {
                "defer": "true"
            }
        }
    ],
    "createdAt": "2025-08-22T20:01:46.809972",
    "lastModifiedAt": "2025-08-22T20:01:46.809972"
}

Creando Snippets con Dependencias

1. Crear el Snippet

Primero, crea un nuevo snippet:

elemental-cms snippets create -s mi-snippet

2. Editar la Especificación

Abre el archivo `mi-snippet.json` generado y agrega tus dependencias:

{
    "_id": ObjectId("..."),
    "name": "mi-snippet",
    "cssDeps": [
        {
            "name": "fontawesome",
            "type": "text/css",
            "url": "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css",
            "meta": {
                "integrity": "sha384-...",
                "crossorigin": "anonymous"
            }
        }
    ],
    "jsDeps": [
        {
            "name": "bootstrap",
            "type": "application/javascript",
            "url": "js/bootstrap.bundle.min.js",
            "meta": {
                "defer": "true"
            }
        }
    ],
    "createdAt": "2025-08-22T20:01:46.809972",
    "lastModifiedAt": "2025-08-22T20:01:46.809972"
}

3. Crear el Contenido HTML

Edita el archivo `mi-snippet.html` con tu contenido:

<div class="mi-snippet">
    <i class="fas fa-home"></i>
    <button class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal">
        Abrir Modal
    </button>
</div>

Tipos y Formatos de Dependencias

Dependencias CSS

Las dependencias CSS pueden ser:

Archivos locales: Almacenados en tu carpeta de assets estáticos
Recursos CDN: Hojas de estilo externas de CDNs
Estilos inline: CSS embebido (no recomendado para hojas de estilo grandes)

Dependencias JavaScript

Las dependencias JavaScript soportan tres tipos:

application/javascript: Archivos JavaScript estándar
module: Módulos ES6
text/css: Archivos CSS (aunque típicamente se usan para hojas de estilo)

Inyección de Dependencias

Cuando los snippets se renderizan, las dependencias se inyectan automáticamente basándose en el parámetro `inject_inline_deps`:

Inyección Automática

Las dependencias se convierten automáticamente en etiquetas HTML:

// Las dependencias CSS se convierten en etiquetas <link>
<link rel="stylesheet" type="text/css" href="https://cdn.example.com/style.css" integrity="sha384-..." crossorigin="anonymous">

// Las dependencias JavaScript se convierten en etiquetas <script>
<script src="js/script.js" type="application/javascript" defer="true"></script>

Proceso de Renderizado

El proceso de renderizado sigue este orden:

Las dependencias CSS se inyectan primero (en el <head> o antes del contenido)
El contenido HTML del snippet se renderiza
Las dependencias JavaScript se inyectan al final (antes del cierre </body>)

Trabajando con Dependencias Globales

Elemental CMS también soporta dependencias globales que se incluyen automáticamente en todas las páginas. Estas funcionan junto con las dependencias específicas de snippets.

Dependencias Globales vs Dependencias de Snippets

Dependencias Globales	Dependencias de Snippets
Aplicadas a todas las páginas automáticamente	Aplicadas solo cuando se usa el snippet
Gestionadas via comandos `global-deps`	Gestionadas dentro de la especificación del snippet
Cargadas en orden específico (por tipo y campo order)	Cargadas cuando el snippet se renderiza
Almacenadas en `GLOBAL_DEPS_FOLDER`	Almacenadas en la especificación JSON del snippet

Combinando Dependencias Globales y de Snippets

Cuando una página se renderiza, se incluyen tanto las dependencias globales como las de snippets:

Las dependencias CSS globales se cargan primero
Las dependencias CSS de snippets se cargan después
El contenido de la página se renderiza
Las dependencias JavaScript globales se cargan
Las dependencias JavaScript de snippets se cargan al final

Mejores Prácticas

1. Usar Nombres Descriptivos

Da a tus dependencias nombres significativos para mejor organización:

{
    "name": "bootstrap-css",
    "type": "text/css",
    "url": "css/bootstrap.min.css"
}

2. Incluir Verificaciones de Integridad

Para recursos externos, incluye hashes de integridad para seguridad:

{
    "name": "jquery",
    "type": "application/javascript",
    "url": "https://code.jquery.com/jquery-3.6.0.min.js",
    "meta": {
        "integrity": "sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK",
        "crossorigin": "anonymous"
    }
}

3. Usar Atributos de Carga Apropiados

Usa atributos meta para controlar el comportamiento de carga:

{
    "name": "analytics",
    "type": "application/javascript",
    "url": "js/analytics.js",
    "meta": {
        "async": "true"
    }
}

4. Minimizar Dependencias

Solo incluye dependencias que realmente uses en el snippet:

Evita incluir frameworks completos para funcionalidad simple
Usa componentes específicos en lugar de librerías completas cuando sea posible
Considera usar dependencias globales para librerías comúnmente usadas

Gestionando Dependencias

Agregando Dependencias

Para agregar dependencias a un snippet existente:

Edita el archivo `.json` del snippet
Agrega objetos de dependencia a los arrays `cssDeps` o `jsDeps`
Haz push del snippet actualizado a la base de datos

Removiendo Dependencias

Para remover dependencias:

Edita el archivo `.json` del snippet
Remueve los objetos de dependencia de los arrays
Haz push del snippet actualizado a la base de datos

Actualizando Dependencias

Para actualizar versiones de dependencias:

Edita el archivo `.json` del snippet
Actualiza el campo `url` con la nueva versión
Actualiza cualquier hash de integridad si es aplicable
Haz push del snippet actualizado a la base de datos

Patrones Comunes de Dependencias

Integración Bootstrap

{
    "cssDeps": [
        {
            "name": "bootstrap-css",
            "type": "text/css",
            "url": "https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css",
            "meta": {
                "integrity": "sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3",
                "crossorigin": "anonymous"
            }
        }
    ],
    "jsDeps": [
        {
            "name": "bootstrap-js",
            "type": "application/javascript",
            "url": "https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js",
            "meta": {
                "integrity": "sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p",
                "crossorigin": "anonymous"
            }
        }
    ]
}

Iconos Font Awesome

{
    "cssDeps": [
        {
            "name": "fontawesome",
            "type": "text/css",
            "url": "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css",
            "meta": {
                "integrity": "sha512-9usAa10IRO0HhonpyAIVpjrylPvoDwiPUiKdWk5t3PyolY1cOd4DSE0Ga+ri4AuTroPR5aQvXU9xC6qOPnzFeg==",
                "crossorigin": "anonymous"
            }
        }
    ]
}

Estilos Locales Personalizados

{
    "cssDeps": [
        {
            "name": "custom-styles",
            "type": "text/css",
            "url": "css/mi-snippet.css"
        }
    ]
}

Solución de Problemas

Dependencias No Se Cargan

Si las dependencias no se están cargando:

Verifica que el parámetro `inject_inline_deps` esté configurado en `true`
Verifica que las URLs sean correctas y accesibles
Revisa la consola del navegador para errores 404
Asegúrate de que el snippet se esté renderizando correctamente

Conflictos de Dependencias

Para resolver conflictos de dependencias:

Verifica dependencias duplicadas entre globales y de snippets
Usa diferentes versiones solo cuando sea necesario
Considera usar dependencias globales para librerías compartidas
Prueba exhaustivamente en diferentes contextos de página

Problemas de Rendimiento

Para optimizar la carga de dependencias:

Usa versiones minificadas de librerías
Considera usar CDNs para mejor caché
Usa atributos `async` o `defer` para scripts no críticos
Combina múltiples archivos CSS pequeños cuando sea posible

Características Avanzadas

Dependencias Condicionales

Puedes cargar dependencias condicionalmente basándote en el contexto de la página:


    <!-- Dependencias específicas para español -->
    <link rel="stylesheet" href="css/spanish-specific.css">

Carga Dinámica de Dependencias

Para escenarios complejos, puedes cargar dependencias dinámicamente:

<script>
    if (typeof jQuery === 'undefined') {
        var script = document.createElement('script');
        script.src = 'js/jquery.min.js';
        document.head.appendChild(script);
    }
</script>

Este sistema integral de gestión de dependencias te permite crear snippets ricos e interactivos mientras mantienes una separación limpia de responsabilidades y rendimiento óptimo.