ContentHub — JS Query Loop

Integración en JavaScript entre un sitio HTML/WordPress y un backend Laravel (Sheets), llamada Js Query Loop (JSQL). Permite consultar entidades del backend y renderizarlas dinámicamente en cualquier página HTML sin necesidad de recargar.

Tabla de contenidos

• Descripción general
• Arquitectura
• Requisitos
• Uso y personalización
• Pasos para publicar
• Instalación local
• Configuración
• Estructura del proyecto

Descripción general

ContentHub actúa como un puente entre el frontend HTML (por ejemplo, WordPress con Bricks Builder) y el backend Laravel. A través del script dist/index.js (JSQL), las páginas pueden:

• Consultar entidades del backend con filtros, orden y paginación.
• Mostrar contenido diferenciado según si el usuario está autenticado o no.
• Restringir rutas a usuarios no autenticados y redirigirlos automáticamente.

Arquitectura

[WordPress / HTML]                  [Laravel / Sheets]
   header.html                  ─────────────────────
   (variables globales JSQL)   |  API REST            |
          │                    |  Autenticación        |
          ▼                    |  Entidades (data)     |
   dist/index.js (JSQL)  ──────────────────────────► |
          │                    └─────────────────────┘
          ▼
   body_footer.html
   (init() con initJSQueryLoop)

El script JSQL se comunica directamente con el backend Laravel. Para que las cookies de sesión funcionen, ambos deben estar bajo el mismo dominio o subdominio compartido.

Requisitos

• Mismo dominio o subdominio compartido entre el HTML y el Laravel. Las cookies de sesión no se comparten entre dominios distintos. Combinaciones válidas:
  • wordpress.dominio.cl y sheets.dominio.cl
  • dominio.cl y api.dominio.cl
• Acceso SSH o FTP al servidor donde corre el sitio HTML/WordPress.
• Git instalado en el equipo local (opcional, pero recomendado).

Uso y personalización

Uso produtivo o servidor: Inicializar JSQL en el sitio HTML/WordPress

Llamar librería por CDN y definir las variables globales e inicializar con initJSQueryLoop:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.js"></script>

<script>
    window.JSQLBaseDomain = '/';
    window.JSQLNonLoggedInIds = ['48d940f9-aeab-4dca-b3be-8fc93bd4417d'];
    window.JSQLNonLoggedRestrictedRoutes = [];
    window.JSQLNonLoggedRedirect = '/';

    window.JSQLCallbacks = (jsql) => {
        // console.log('callback', jsql);
    }

    let jsqlArr;
    document.addEventListener('DOMContentLoaded', () => {
        const userId = localStorage.getItem('jsql_sheets_user_id');
        jsqlArr = init(userId);
    });

    function init(userId) {
        console.log('jsqlArr Init...', userId);
        return initJSQueryLoop([
            {
                entityType: 'nombre_de_entidad',   // Entidad del backend Laravel
                cssSelector: '.mi-contenedor',      // Selector CSS donde se renderiza
                max: 12,                            // Máximo de resultados por página
                filters: [
                    {
                        colNameOrId: 'columna',
                        valueA: 'valor',
                        type: 'EQUAL'               // EQUAL | IN | BETWEEN | etc.
                    }
                ]
            }
        ]);
    }
</script>

Opción 2: Para uso local, crear una instancia personalizada

Copiar los archivos de examples/ a una nueva carpeta dentro de custom/ y adaptarlos al proyecto:

cp -r examples/ custom/mi_proyecto/

Pasos para publicar

El paquete se publica en npmjs.com bajo el nombre coderhubspa_content_hub.

1. Actualizar la versión en package.json

Incrementar la versión siguiendo semver:

# Parche (bug fix): 1.2.0 → 1.2.1
npm version patch

# Feature menor compatible: 1.2.0 → 1.3.0
npm version minor

# Cambio mayor / breaking: 1.2.0 → 2.0.0
npm version major

Esto actualiza package.json y crea un commit + tag de Git automáticamente.

2. Configurar el token de publicación (solo la primera vez)

La cuenta npm requiere 2FA. Para publicar desde CLI se necesita un token de automatización:

1. Ir a https://www.npmjs.com → avatar → Access Tokens
2. Generate New Token → Granular Access Token
3. Asignar permiso Read and write sobre el paquete coderhubspa_content_hub
4. Copiar el token y ejecutar:

npm config set //registry.npmjs.org/:_authToken TU_TOKEN_AQUI

Esto queda guardado en ~/.npmrc para futuras publicaciones.

3. Publicar el paquete

npm publish

4. Subir el tag y el commit al repositorio

git push origin main --tags

5. Verificar la publicación

Confirmar que la nueva versión aparece en: https://www.npmjs.com/package/coderhubspa_content_hub

6. Actualizar la URL del CDN en el sitio

En el snippet de inicialización, actualizar el número de versión en la URL de jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.js"></script>

jsDelivr sirve automáticamente cualquier versión publicada en npm. También se puede usar @latest para apuntar siempre a la última versión, aunque no es recomendable en producción.

Instalación local

1. Clonar el repositorio:

   git clone https://github.com/CoderhubSpA/sheets_wordpress_integration.git
   cd sheets_wordpress_integration

2. Levantar el entorno de desarrollo apuntando el servidor web local a la carpeta del proyecto (Apache, Nginx, o PHP built-in server):

   php -S localhost:8080

   Luego abrir http://localhost:8080/index.php para ver la demo.

Configuración

Variables globales JS (header.html)

Estas variables deben definirse antes de cargar dist/index.js:

<script>
    // Dominio base del backend Laravel. Usar '/' si está en el mismo dominio.
    window.JSQLBaseDomain = '/';

    // IDs de entidades visibles sin autenticación
    window.JSQLNonLoggedInIds = ['48d940f9-aeab-4dca-b3be-8fc93bd4417d'];

    // Rutas restringidas para usuarios no autenticados (dejar vacío si no aplica)
    window.JSQLNonLoggedRestrictedRoutes = [];

    // Ruta de redirección si no está autenticado
    window.JSQLNonLoggedRedirect = '/';

    // Callback global ejecutado después de cada consulta
    window.JSQLCallbacks = (jsql) => {
        // console.log('callback', jsql);
    };
</script>

Estructura del proyecto

sheets_wordpress_integration/
├── dist/                    # Archivos compilados listos para producción
│   ├── index.js             # Script principal de JSQL
│   ├── header.html          # Snippet de cabecera (variables globales + estilos)
│   ├── body_header.html     # Snippet de inicio de body
│   └── body_footer.html     # Snippet de pie de body (init de JSQL)
├── examples/                # Ejemplos de uso
│   ├── header.html
│   ├── body_header.html
│   └── body_footer.html
├── custom/                  # Instancias personalizadas por proyecto
│   ├── sernatur01_audiovisual/
│   └── lr_participacion/
├── index.php                # Demo / entorno de desarrollo
├── index_body_footer.js     # Ejemplo de configuración de initJSQueryLoop
└── package.json