Tiempo de Ejecución en Cliente y Personalización

Tiempo de Ejecución en Cliente y Personalización

docmd incluye un script de ejecución en cliente ligero y headless, docmd-runtime.js, que se incorpora automáticamente en todas las plantillas (incluyendo el diseño por defecto y temas como summer).

Este entorno expone la API de navegador window.docmd, permitiendo actualizar variables dinámicamente según la autenticación del usuario, el entorno seleccionado o entradas de formularios sin necesidad de recargar la página.

Declarar Variables como Dinámicas

En su docmd.config.json, especifique qué claves son dinámicas:

{
  "variables": {
    "dynamic": [
      "user.name",
      "user.apiKey",
      "selectedProject",
      "activeRegion"
    ]
  }
}

Al compilar, docmd envuelve cada variable dinámica (o que empiece por user.) con un elemento marcador reactivo:

pk_test_sample

API JavaScript de Navegador: window.docmd

La API del cliente ofrece funciones claras y directas:

Definir Variables

window.docmd.var.set(key, val)
Actualiza variables en todo el DOM y en los bloques de código en tiempo real.

Obtener Variable

window.docmd.var.get(key)
Devuelve el valor activo de una variable registrada.

Listar Todas

window.docmd.var.list()
Devuelve un objeto con todas las variables dinámicas registradas.

Sincronizar DOM

window.docmd.var.sync()
Vuelve a examinar el HTML inyectado para rehidratar los marcadores.

Ejemplo: Actualizar Variables

// Establecer una variable individual
window.docmd.var.set('user.apiKey', 'sk_live_99882244');

// Establecer múltiples variables a la vez
window.docmd.var.set({
  'user.name': 'Sarah Connor',
  'activeRegion': 'eu-central-1'
});

Todos los elementos <span data-docmd-var="..."> y fragmentos de código se actualizan en el acto.

Demostración Interactiva con Bloques de Código

Un caso de uso destacado es permitir a los desarrolladores probar comandos API con su propia clave:

### Autenticación con la API

Ejecute el siguiente comando en su terminal:

```bash
curl -X GET https://api.acme.com/v1/profile \
  -H "Authorization: Bearer {{ user.apiKey || 'SU_CLAVE_API' }}"
```

Demostración Interactiva en Vivo con Variables

Utilice el siguiente playground para mutar user.apiKey en el entorno de ejecución del navegador. Al ejecutar el código o modificar la clave, docmd-runtime actualiza inmediatamente todas las referencias del documento:

js Probador Interactivo de Variables

El siguiente comando curl se actualiza dinámicamente en tiempo real:

curl -X GET https://api.acme.com/v1/profile \
  -H "Authorization: Bearer SU_CLAVE_API"
Inmunidad a XSS en el DOM

El motor docmd-runtime.js actualiza los elementos reactivos del DOM estrictamente mediante .textContent. Los valores de variables nunca se analizan como HTML sin procesar o scripts ejecutables, previniendo ataques de inyección basados en el DOM incluso con entradas dinámicas del usuario.

Integración con Frameworks

Vanilla JavaScript
React / Next.js
Vue / Nuxt
function onUserLogin(session) {
  window.docmd.var.set({
    'user.name': session.fullName,
    'user.apiKey': session.activeToken,
    'user.orgId': session.organisationId
  });
}
import { useEffect } from 'react';

export function DocsPersonaliser({ user }: { user: any }) {
  useEffect(() => {
    if (typeof window !== 'undefined' && (window as any).docmd) {
      (window as any).docmd.var.set({
        'user.name': user.name,
        'user.apiKey': user.apiKey
      });
    }
  }, [user]);

  return null;
}
<script setup>
import { watchEffect } from 'vue';

const props = defineProps(['currentUser']);

watchEffect(() => {
  if (typeof window !== 'undefined' && window.docmd) {
    window.docmd.var.set({
      'user.name': props.currentUser?.name,
      'user.apiKey': props.currentUser?.token
    });
  }
});
</script>

Escuchar Cambios de Variables

Puede reaccionar a los eventos emitidos por el bus del cliente:

window.addEventListener('docmd:variable-change', (event) => {
  const { key, value } = event.detail;
  console.log(`Variable ${key} modificada a:`, value);
});

Sincronización entre Marcos (iFrames y Portales)

Si la documentación se aloja en un iframe dentro de su aplicación, el portal puede enviar variables mediante postMessage:

const docIframe = document.getElementById('docs-frame');
docIframe.contentWindow.postMessage({
  type: 'docmd:set-variables',
  variables: {
    'user.name': 'Alex',
    'user.apiKey': 'sk_live_449911'
  }
}, '*');
Arquitectura Headless Independiente

docmd-runtime.js opera exclusivamente mediante marcadores de datos (data-docmd-var), por lo que no interfiere con estilos CSS, transiciones SPA o plugins de terceros.