Características

Rápido y Ligero

Menos de 5KB minificado y gzipped. Sin dependencias externas, haciendo que tu sitio web se mantenga veloz y eficiente.

Actualización Ordenada

Controla el orden en que se actualizan los elementos para una experiencia de usuario fluida y profesional.

Caché Inteligente

Precarga y almacena en caché el contenido para una actualización instantánea cuando sea necesario, mejorando significativamente el rendimiento.

Fácil Implementación

API sencilla y atributos intuitivos para una integración rápida en cualquier proyecto web sin complicaciones.

Personalizable

Configura múltiples instancias con diferentes manejadores para actualizar partes específicas de tu sitio con total control.

Depuración Integrada

Sistema de logging con códigos de colores para facilitar el desarrollo y la depuración durante todo el proceso.

Componentes Web

Incluye componentes web personalizados como SwappitButton para facilitar la actualización de contenido a través de enlaces existentes.

Seguro y Confiable

Diseñado para funcionar con rutas internas relativas, evitando problemas de seguridad y asegurando un comportamiento predecible.

Instalación

Comienza a utilizar Swappit en tu proyecto en segundos con cualquiera de estas opciones.

NPM

1. Instala el paquete en tu proyecto:

bash

npm install @soyleninjs/swappit

2. Importa y usa en tu código:

javascript

// Usando ES modules
import Swappit from '@soyleninjs/swappit';
// o puedes hacer uso de un cdn sin instalarlo
import Swappit from "https://esm.sh/@soyleninjs/swappit";

// O usando CommonJS
const Swappit = require('@soyleninjs/swappit');

CDN o Descarga Directa

Opción 1: Incluye desde CDN:

html

<script src="https://cdn.jsdelivr.net/npm/@soyleninjs/swappit/swappit.min.js"></script>

Opción 2: Descarga directa:

Descarga swappit.min.js desde el repositorio de GitHub
Copia el archivo a tu proyecto e inclúyelo en tu HTML:

html

<script src="ruta/a/tu/proyecto/swappit.min.js"></script>

Cómo Funciona

Swappit simplifica la actualización dinámica de contenido con una API intuitiva.

1 Define tus elementos HTML

html

<div data-mi-app-update="header">
    <h1>Título original</h1>
</div>

<div data-mi-app-update="content">
    <p>Contenido original</p>
</div>

2 Inicializa Swappit y actualiza

javascript

// Crear una instancia de Swappit
const appBasico = new Swappit('mi-app', true);

// Función para actualizar contenido
function actualizarContenidoBasico() {
    appBasico.update('examples/contenido-nuevo.html');
}

// Función para restaurar contenido original
function restaurarContenidoBasico() {
    appBasico.update('./');
}

3 Estructura de las páginas de destino

Para que Swappit funcione correctamente, las páginas a las que haces peticiones deben tener elementos con los mismos atributos data:

Página principal:

html

<div data-mi-app-update="header">
    Encabezado original
</div>
<div data-mi-app-update="sidebar">
    Barra lateral original
</div>
<div data-mi-app-update="content">
    Contenido original
</div>

Página de destino:

html

<!DOCTYPE html>
<html>
<body>
    <div data-mi-app-update="header">
        Nuevo encabezado
    </div>
    <div data-mi-app-update="content">
        Nuevo contenido
    </div>
    <div data-mi-app-update="footer">
        Este elemento será ignorado
    </div>
</body>
</html>

Resultado después de actualizar:

El elemento header se actualizará con "Nuevo encabezado"
El elemento content se actualizará con "Nuevo contenido"
El elemento sidebar permanecerá sin cambios (no tiene correspondencia en la página de destino)
El elemento footer de la página de destino será ignorado (no tiene correspondencia en la página principal)

Importante: Solo se actualizarán los elementos que tengan correspondencia en ambas páginas. El resto del contenido permanecerá sin cambios.

Demo

Título de demostración

Este es el contenido original de la demostración. Haz clic en el botón "Actualizar" para ver Swappit en acción.

Funcionalidades adicionales

Actualización con Orden Específico

html

<div data-mi-app-update="section1" data-mi-app-update-order="2">
    Sección 1 (Orden: 2)
</div>
<div data-mi-app-update="section2" data-mi-app-update-order="1">
    Sección 2 (Orden: 1)
</div>

Precarga de Múltiples URLs

javascript

// Precargar contenido
app.preloadContents([
    'header.html',
    'main.html',
    'footer.html'
]);

// Más tarde, actualizar solo una parte
app.update('header.html');

Escucha de Eventos

javascript

window.addEventListener('mi-app::update', () => {
    console.log('Contenido actualizado');
    // Ejecutar código después de la actualización
});

Opciones de configuración

Personaliza Swappit según tus necesidades con estas opciones de configuración.

Constructor

javascript

new Swappit(handle, log = false)

Parámetro	Tipo	Descripción
`handle`	string	Identificador único para la instancia (obligatorio)
`log`	boolean	Activa/desactiva los logs de la consola (opcional, default: false)

Atributos

Atributo	Descripción
`data-[handle]-update`	Identificador del elemento a actualizar
`data-[handle]-update-order`	Orden de actualización (opcional)

Métodos

Métodos de instancia

Método	Descripción
`update(url, loadFromCache = true)`	Actualiza el contenido desde una URL específica: `url`: Ruta relativa a la página que contiene el contenido a cargar `loadFromCache`: Determina si se debe utilizar la versión en caché (si existe) o forzar una nueva descarga: `true` (valor predeterminado): Usa la versión en caché si está disponible `false`: Ignora la caché y realiza una nueva petición fetch a la URL
`preloadContents(arrayUrls)`	Precarga el contenido de múltiples URLs para utilizarlo posteriormente

Métodos estáticos

Método	Descripción
`updateScriptByContent(arrayScriptsNodes)`	Actualiza scripts por contenido
`updateScriptBySrc(matchUrl)`	Actualiza scripts por URL de origen

Eventos

Swappit emite un evento personalizado cuando se completa una actualización:

javascript

window.addEventListener('mi-handle::update', () => {
  console.log('Contenido actualizado');
});

Logging

Swappit incluye un sistema de logging con diferentes niveles:

Info (azul): Información general
Success (verde): Operaciones exitosas
Warning (amarillo): Advertencias
Error (rojo): Errores

Para activar los logs, inicializa el componente con el parámetro log en true:

javascript

const app = new Swappit('mi-app', true);

SwappitButton

¿No quieres escribir JavaScript? Swappit incluye un custom element que facilita la integración con enlaces existentes para actualizar contenido sin recargar la página.

Uso Simple

Solo necesitas envolver tus enlaces existentes con el componente y automáticamente capturará clics para actualizar contenido sin recargar la página.

Configurable

Controla el comportamiento con atributos simples: activar logs, precargar contenido o forzar nuevas descargas cuando sea necesario.

Rutas Seguras

Solo acepta rutas relativas internas para garantizar la seguridad y evitar problemas de origen cruzado.

Reutilización de Instancias

Comparte automáticamente la misma instancia de Swappit entre múltiples botones con el mismo handle, optimizando la memoria y rendimiento.

Demostración

Sección de navegación

Esta sección se actualizará sin recargar la página al hacer clic en los botones de abajo.

Contenido principal

El contenido se actualizará dependiendo del botón que selecciones.

Página 1

Página 2

Página 3 (Forzar descarga)

Ejemplo completo:

html

<!-- Elementos a actualizar -->
<div data-swappit-button-update="header">
    <h2>Sección de navegación</h2>
    <p>Esta sección se actualizará...</p>
</div>

<div data-swappit-button-update="content">
    <h2>Contenido principal</h2>
    <p>El contenido se actualizará...</p>
</div>

<!-- Menú de navegación con SwappitButton -->
<nav>
  <swappit-button data-handle="swappit-button" data-log="true">
      <a href="./pagina1.html">Página 1</a>
  </swappit-button>
  
  <swappit-button data-handle="swappit-button" data-preload="false">
      <a href="./pagina2.html">Página 2</a>
  </swappit-button>
  
  <swappit-button data-handle="swappit-button" data-load-from-cache="false">
      <a href="./pagina3.html">Página 3 (Forzar descarga)</a>
  </swappit-button>
</nav>

JavaScript (opcional):

No es necesario escribir JavaScript adicional para utilizar el componente, pero puede interactuar con la instancia de Swappit si lo desea:

javascript

// Acceder a la instancia de Swappit asociada a los botones
 const swappitButton = Swappit.instances.get("swappit-button");
 
 // Escuchar eventos de actualización
 window.addEventListener("swappit:swappit-button:afterUpdate", () => {
   console.log("Navegación completada");
 });

Uso básico

html

<swappit-button data-handle="mi-app">
  <a href="./mi-pagina.html">Ir a Mi Página</a>
</swappit-button>

Comportamiento

El componente debe contener un único elemento <a> con un atributo href válido
Solo acepta rutas relativas internas (que empiecen con ./ o /)
Intercepta los clics y utiliza Swappit para actualizar el contenido sin recargar la página
Reutiliza instancias existentes de Swappit o crea una nueva si no existe

Atributos disponibles

El componente acepta los siguientes atributos para personalizar su comportamiento:

Atributo	Tipo	Valor predeterminado	Obligatorio	Descripción
`data-handle`	string	N/A	Si	Identificador único para la instancia de Swappit que se utilizará
`data-log`	boolean	false	No	Activa/desactiva los logs para esta instancia
`data-preload`	boolean	true	No	Precarga automáticamente el contenido del enlace
`data-load-from-cache`	boolean	true	No	Si es `true` (predeterminado) usa la versión en caché. Solo es necesario especificar `false` para forzar una nueva descarga

Demos

Explora las capacidades de Swappit con estos ejemplos prácticos e interactivos.

Actualización Básica de Contenido

Contenido Original

Título original

Contenido original

Código del ejemplo:

javascript

// Crear una instancia de Swappit
const appBasico = new Swappit('mi-app', true);

// Función para actualizar contenido
function actualizarContenidoBasico() {
    appBasico.update('examples/contenido-nuevo.html');
}

// Función para restaurar contenido original
function restaurarContenidoBasico() {
    appBasico.update('./');
}

html

<!-- Definir los elementos con los atributos data-mi-app-update -->
<div data-mi-app-update="header">
    <h1>Título original</h1>
</div>

<div data-mi-app-update="content">
    <p>Contenido original</p>
</div>

Actualización con Orden Específico

Contenido Original

Sección 1 (Orden: 2)

Sección 2 (Orden: 1)

Sección 3 (Orden: 3)

Código del ejemplo:

javascript

// Crear una instancia de Swappit
const appOrdenado = new Swappit('mi-app-orden', true);

// Función para actualizar contenido con orden
function actualizarContenidoOrdenado() {
    appOrdenado.update('examples/contenido-ordenado.html');
}

// Función para restaurar contenido original
function restaurarContenidoOrdenado() {
    appOrdenado.update('./');
}

html

<!-- Definir los elementos con atributos de orden -->
<div data-mi-app-orden-update="section1" data-mi-app-orden-update-order="2">
    Sección 1 (Orden: 2)
</div>

<div data-mi-app-orden-update="section2" data-mi-app-orden-update-order="1">
    Sección 2 (Orden: 1)
</div>

<div data-mi-app-orden-update="section3" data-mi-app-orden-update-order="3">
    Sección 3 (Orden: 3)
</div>

Precarga de Múltiples URLs

Header

Contenido del header...

Contenido Principal

Contenido principal...

Footer

Contenido del footer...

Código del ejemplo:

javascript

// Crear una instancia de Swappit
const appPrecarga = new Swappit('mi-app-precarga', true);

// Precargar todo el contenido
appPrecarga.preloadContents([
    'examples/header.html',
    'examples/main.html',
    'examples/footer.html'
]);

// Funciones para actualizar cada sección
function actualizarHeader() {
    appPrecarga.update('examples/header.html');
}

function actualizarMain() {
    appPrecarga.update('examples/main.html');
}

function actualizarFooter() {
    appPrecarga.update('examples/footer.html');
}

// Función para restaurar todo
function restaurarPrecarga() {
    appPrecarga.update('./');
}

html

<!-- Definir los elementos para la precarga -->
<div data-mi-app-precarga-update="header">
    <h2>Header</h2>
    <p>Contenido del header...</p>
</div>

<div data-mi-app-precarga-update="main">
    <h2>Contenido Principal</h2>
    <p>Contenido principal...</p>
</div>

<div data-mi-app-precarga-update="footer">
    <h2>Footer</h2>
    <p>Contenido del footer...</p>
</div>

Documentación

Consulta la documentación completa para aprovechar al máximo Swappit.

Recursos Completos

Documentación técnica para sacar el máximo provecho de Swappit en tus proyectos.

Ver Documentación