Título original

Contenido original

``` **JavaScript:** ```javascript const appBasico = new Swappit('mi-app'); function actualizarContenido() { appBasico.update('./contenido-nuevo.html'); } ``` ### Ejemplo 2: Actualización con orden específico Los elementos con `data-[handle]-update-order` se actualizan primero (de menor a mayor). Los que no tienen este atributo se actualizan al final. **HTML:** ```html

Sección 1 (Orden: 2)

Sección 2 (Orden: 1)

Sección 3 (Sin orden, se actualiza al final)

``` El orden de ejecución será: section2 → section1 → section3. **JavaScript:** ```javascript const appOrdenado = new Swappit('mi-app-orden'); appOrdenado.update('./contenido-ordenado.html'); ``` ### Ejemplo 3: Precarga de múltiples URLs **HTML:** ```html

...

``` **JavaScript:** ```javascript const appPrecarga = new Swappit('mi-app-precarga'); appPrecarga.preloadContents(['./header.html', './main.html', './footer.html']); function actualizarHeader() { appPrecarga.update('./header.html'); } function actualizarMain() { appPrecarga.update('./main.html'); } function actualizarFooter() { appPrecarga.update('./footer.html', false); } ``` ## Opciones de configuración ```javascript new Swappit(handle, options = {}) ``` | Parámetro | Tipo | Descripción | |-----------|------|-------------| | `handle` | string | Identificador único para la instancia (obligatorio) | | `options` | object | Objeto con todas las opciones de configuración (opcional) | Todas las opciones de configuración se pasan dentro del objeto `options`. No hay parámetros adicionales fuera de él. ### Opciones disponibles (`options`) | Opción | Tipo | Default | Descripción | |--------|------|---------|-------------| | `log` | boolean | `false` | Activa/desactiva los logs de la consola | | `updateUrl` | boolean | `false` | Actualiza la URL en la barra del navegador al hacer update | | `enableHistory` | boolean | `false` | Habilita navegación con botones adelante/atrás del navegador. **Requiere `updateUrl: true`** | | `preload` | string\|false | `false` | Modo de precarga por defecto para links con `data-swappit-handle`. Valores: `false`, `"hover"`, `"instant"` | **Notas:** - `enableHistory: true` **no tiene efecto** si `updateUrl` no está en `true`. El listener de `popstate` solo se registra cuando ambas opciones están activas - `updateUrl: true` + `enableHistory: false`: actualiza la URL en cada navegación sin agregar entradas al historial (usa `replaceState`) - `updateUrl: true` + `enableHistory: true`: actualiza la URL y agrega cada navegación al historial del navegador (usa `pushState`), habilitando los botones adelante/atrás - Solo una instancia puede controlar el historial a la vez. Intentar crear una segunda instancia con `updateUrl: true` + `enableHistory: true` lanzará un error - `preload`: define el comportamiento por defecto para todos los links gestionados, pero puede ser sobreescrito individualmente con el atributo `data-preload` en cada link ### Atributos de datos para elementos que se actualizan | Atributo | Descripción | |----------|-------------| | `data-[handle]-update` | Identificador del elemento a actualizar (obligatorio) | | `data-[handle]-update-order` | Orden de actualización (opcional, numérico). Los elementos **con** este atributo se actualizan primero, de menor a mayor valor; los elementos **sin** este atributo se actualizan al final | ### Atributos de datos para links (``) | Atributo | Tipo | Descripción | |----------|------|-------------| | `data-swappit-handle` | string | Conecta el link con una instancia Swappit (obligatorio) | | `data-preload` | string | Modo de precarga: `"instant"` (inmediata al cargar), `"hover"` (al pasar mouse/touch), o sin definir (solo al hacer click) | | `data-use-cache` | boolean | Si es `"true"` usa caché, si es `"false"` fuerza nueva descarga al hacer click. Default: `true` | ## Métodos ### Métodos de instancia | Método | Descripción | |--------|-------------| | `update(url, useCache = true)` | Carga el HTML de `url` y reemplaza las regiones del DOM correspondientes.
- `url`: Ruta relativa (debe empezar con `/` o `./`)
- `useCache`: `true` usa caché si existe, `false` fuerza una nueva descarga | | `preloadContents(arrayUrls)` | Precarga en paralelo el contenido de un array de URLs relativas y las almacena en caché sin actualizar el DOM | | `reinit(options = {})` | Actualiza las opciones de la instancia (merge) y reinicializa sus handlers y el observer del DOM.
- `options`: Objeto con las propiedades que se desean sobreescribir | | `destroy()` | Destruye la instancia de forma definitiva: limpia la caché, cancela peticiones pendientes, elimina todos los listeners y el observer del DOM, y la borra del registro `Swappit.instances` | ### Métodos estáticos | Método | Descripción | |--------|-------------| | `Swappit.updateScriptByContent(arrayScriptsNodes)` | Recibe un array de nodos ` Ir a Página 1 Ir a Página 2 ``` ### Configuración de precarga por link Cada link puede tener su propia configuración de precarga: ```html Página 1 Página 2 Página 3 Página 4 ``` ### Precarga predeterminada para todos los links Puedes definir un modo de precarga predeterminado para todos los links al crear la instancia: ```javascript const app = new Swappit('mi-app', { preload: 'hover' // Todos los links harán precarga al hover por defecto }); ``` Los links individuales pueden sobrescribir este comportamiento con su propio `data-preload`: ```html Página 1 Página 2 ``` ### Detección automática de nuevos links Swappit observa cambios en el DOM y configura automáticamente los nuevos links que se agreguen dinámicamente: ```javascript // Los nuevos links se configurarán automáticamente document.querySelector('#contenedor').innerHTML = ` Nueva Página `; ``` ### Ventajas de este método - **Zero-config**: Solo agrega el atributo `data-swappit-handle` a tus links - **Precarga flexible**: Configura precarga individual o global - **Detección automática**: Los links dinámicos se configuran automáticamente - **Control de caché**: Decide si usar caché o forzar descarga por link ## Swappit Instance Swappit incluye el custom element `` para crear instancias Swappit de forma declarativa usando atributos HTML. ### Uso básico ```html ``` ### Atributos disponibles | Atributo | Tipo | Descripción | Valor predeterminado | |----------|------|-------------|----------------------| | `data-handle` | string | Identificador de la instancia Swappit (obligatorio) | N/A | | `data-log` | boolean (presencia) | Activa logs para la instancia | `false` | | `data-update-url` | boolean (presencia) | Actualiza la URL del navegador | `false` | | `data-enable-history` | boolean (presencia) | Habilita navegación con botones del navegador | `false` | | `data-preload` | string | Modo de precarga: `"instant"`, `"hover"` | `false` | **Nota**: Los atributos `data-log`, `data-update-url` y `data-enable-history` son de tipo booleano por presencia: se activan con solo incluirlos en el elemento, sin necesidad de asignarles un valor. ### Comportamiento 1. **Crea o reinicia una instancia**: Si no existe una instancia con ese `data-handle`, la crea. Si ya existe, la reinicia con las nuevas opciones. 2. **Configuración declarativa**: Todos los atributos se mapean directamente a las opciones de Swappit. 3. **Funciona con links automáticos**: Los links con `data-swappit-handle` que coincidan con el handle se configuran automáticamente. 4. **Reinicio automático**: Si el componente ya tiene una instancia activa con ese handle, llama a `reinit()` para actualizar la configuración. ### Ejemplo completo ```html Ejemplo Swappit Instance

Encabezado Original

Contenido original de la página

``` ## Método reinit() El método `reinit()` permite actualizar la configuración de una instancia Swappit existente y volver a inicializar sus handlers y observadores del DOM. ### Sintaxis ```javascript instance.reinit(options) ``` ### Parámetros - `options` (object): Objeto con opciones para actualizar. Se hace merge con las opciones existentes; solo las propiedades que incluyas se sobreescriben. ### Comportamiento 1. **Actualiza opciones**: Hace merge de las nuevas opciones con las existentes 2. **Reinicia handlers**: Vuelve a configurar el handler de historial según las nuevas opciones 3. **Reinicia observer**: Vuelve a observar el DOM para detectar links con el handle 4. **Emite evento**: Dispara el evento `swappit:[handle]:reinit` ### Ejemplo de uso ```javascript const app = new Swappit('mi-app', { updateUrl: false, preload: false }); // Después de un tiempo, cambiar la configuración app.reinit({ log: true, updateUrl: true, enableHistory: true, preload: 'hover' }); // Ahora la instancia tiene: // - log: true // - updateUrl: true // - enableHistory: true // - preload: 'hover' ``` ### Cuándo usar reinit() - Cuando necesitas cambiar opciones dinámicamente - Cuando `` detecta que ya existe una instancia con ese handle - Al cambiar entre modos (por ejemplo, de desarrollo a producción) ## Método destroy() El método `destroy()` destruye completamente una instancia Swappit, liberando todos sus recursos. ### Sintaxis ```javascript instance.destroy() ``` ### Comportamiento 1. **Marca la instancia como destruida**: Bloquea el uso de `update()`, `reinit()` y `preloadContents()` 2. **Limpia la caché**: Elimina todo el contenido almacenado 3. **Cancela peticiones pendientes**: Incrementa el `requestId` para ignorar respuestas en vuelo 4. **Elimina el listener de historial**: Desregistra el evento `popstate` si estaba activo 5. **Desconecta el MutationObserver**: Deja de observar nuevos links en el DOM 6. **Limpia listeners de links**: Elimina todos los eventos de click, hover y touch de los links gestionados 7. **Libera el control del historial**: Si esta instancia era la controladora del historial, la libera 8. **Emite evento**: Dispara `swappit:[handle]:destroy` 9. **Elimina del registro**: Borra la instancia de `Swappit.instances` ### Ejemplo de uso ```javascript const app = new Swappit('mi-app'); // Más tarde, cuando ya no necesites la instancia app.destroy(); // Puedes crear una nueva instancia con el mismo handle const appNueva = new Swappit('mi-app'); ``` ## Manejo de scripts **IMPORTANTE**: Los scripts dentro de los elementos actualizados **NO se ejecutan automáticamente**. ### Comportamiento actual Cuando Swappit actualiza el DOM: - Los elementos HTML se reemplazan correctamente - Los `

` **NO se ejecutan automáticamente** ### Cómo ejecutar scripts manualmente Si necesitas que los scripts se ejecuten después de actualizar el contenido, usa los métodos estáticos en el evento `update:after`: #### 1. Actualizar scripts inline (por contenido) ```javascript window.addEventListener('swappit:mi-app:update:after', () => { // Seleccionar scripts dentro de los elementos actualizados const scripts = document.querySelectorAll('[data-mi-app-update] script'); // Ejecutarlos recreándolos en el DOM Swappit.updateScriptByContent(Array.from(scripts)); }); ``` #### 2. Actualizar scripts externos (por src) ```javascript window.addEventListener('swappit:mi-app:update:after', () => { // Recargar todos los scripts que contengan "analytics" en su URL // Se agrega un timestamp para forzar la recarga Swappit.updateScriptBySrc('analytics'); }); ``` ### Ejemplo completo ```html <script> const app = new Swappit('mi-app', { log: true }); window.addEventListener('swappit:mi-app:update:after', (e) => { console.log('Contenido actualizado de:', e.detail.url); // Ejecutar scripts inline dentro de los elementos actualizados const inlineScripts = document.querySelectorAll('[data-mi-app-update] script:not([src])'); if (inlineScripts.length > 0) { Swappit.updateScriptByContent(Array.from(inlineScripts)); } // Recargar scripts externos específicos Swappit.updateScriptBySrc('mi-libreria.js'); }); ` que llama a `reinit()` automáticamente | | `` no crea la instancia | Falta atributo `data-handle` | El atributo `data-handle` es obligatorio | | Los scripts no se ejecutan | Scripts no se ejecutan automáticamente por diseño | Usa `Swappit.updateScriptByContent()` o `Swappit.updateScriptBySrc()` en el evento `update:after` | | La precarga no funciona | Valor incorrecto en `data-preload` | Usa `"instant"` o `"hover"` (con comillas en el atributo HTML) | | Los botones adelante/atrás no funcionan | Falta configuración de historial | Activa `updateUrl: true` y `enableHistory: true` en las opciones | | Error "Solo una instancia puede controlar el historial" | Dos instancias con `updateUrl` y `enableHistory` activos | Solo una instancia puede tener `updateUrl: true` + `enableHistory: true` simultáneamente | | Links dinámicos no se configuran | Error en el observer | El observer se inicia automáticamente. Activa `log: true` para ver mensajes de depuración | | El caché no se actualiza | `useCache` está en `true` por defecto | Pasa `false` como segundo argumento: `update(url, false)` para forzar nueva descarga | | La instancia no toma las nuevas opciones | Las opciones se definen al crear la instancia | Usa el método `reinit(options)` para actualizar opciones dinámicamente | | Eventos no se escuchan correctamente | Nombre de evento desactualizado | Los eventos ahora usan el formato `swappit:[handle]:update:after`, `swappit:[handle]:update:before`, etc. | --- _Source: https://npm.io/package/@soyleninjs/swappit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._