Actualiza sin recargar, siente la fluidez, haz Swappit.
Swappit es una librería JavaScript diseñada para facilitar la actualización parcial o total del contenido HTML de tu sitio web sin recargar la página. Su enfoque declarativo permite integrar funcionalidades modernas de navegación y experiencia de usuario sin la complejidad de un framework completo o arquitectura SPA. Ideal para proyectos que requieren velocidad, simplicidad y compatibilidad con plataformas. Swappit detecta y reemplaza dinámicamente elementos del DOM, manteniendo scripts de terceros funcionales y ofreciendo una navegación fluida y eficiente.
Menos de 5KB minificado y gzipped. Sin dependencias externas, haciendo que tu sitio web se mantenga veloz y eficiente.
Controla el orden en que se actualizan los elementos para una experiencia de usuario fluida y profesional.
Precarga y almacena en caché el contenido para una actualización instantánea cuando sea necesario, mejorando significativamente el rendimiento.
API sencilla y atributos intuitivos para una integración rápida en cualquier proyecto web sin complicaciones.
Configura múltiples instancias con diferentes manejadores para actualizar partes específicas de tu sitio con total control.
Sistema de logging con códigos de colores para facilitar el desarrollo y la depuración durante todo el proceso.
Incluye componentes web personalizados como SwappitButton para facilitar la actualización de contenido a través de enlaces existentes.
Diseñado para funcionar con rutas internas relativas, evitando problemas de seguridad y asegurando un comportamiento predecible.
Comienza a utilizar Swappit en tu proyecto en segundos con cualquiera de estas opciones.
1. Instala el paquete en tu proyecto:
npm install @soyleninjs/swappit
2. Importa y usa en tu código:
// 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');
Opción 1: Incluye desde CDN:
<script src="https://cdn.jsdelivr.net/npm/@soyleninjs/swappit/swappit.min.js"></script>
Opción 2: Descarga directa:
swappit.min.js
desde el repositorio de GitHub<script src="ruta/a/tu/proyecto/swappit.min.js"></script>
Swappit simplifica la actualización dinámica de contenido con una API intuitiva.
<div data-mi-app-update="header">
<h1>Título original</h1>
</div>
<div data-mi-app-update="content">
<p>Contenido original</p>
</div>
// 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('./');
}
Para que Swappit funcione correctamente, las páginas a las que haces peticiones deben tener elementos con los mismos atributos data:
<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>
<!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>
header
se actualizará con "Nuevo encabezado"content
se actualizará con "Nuevo contenido"sidebar
permanecerá sin cambios (no tiene correspondencia en la página de destino)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.
Este es el contenido original de la demostración. Haz clic en el botón "Actualizar" para ver Swappit en acción.
<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>
// Precargar contenido
app.preloadContents([
'header.html',
'main.html',
'footer.html'
]);
// Más tarde, actualizar solo una parte
app.update('header.html');
window.addEventListener('mi-app::update', () => {
console.log('Contenido actualizado');
// Ejecutar código después de la actualización
});
Personaliza Swappit según tus necesidades con estas opciones de configuración.
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) |
Atributo | Descripción |
---|---|
data-[handle]-update |
Identificador del elemento a actualizar |
data-[handle]-update-order |
Orden de actualización (opcional) |
Método | Descripción |
---|---|
update(url, loadFromCache = true) |
Actualiza el contenido desde una URL específica:
|
preloadContents(arrayUrls) |
Precarga el contenido de múltiples URLs para utilizarlo posteriormente |
Método | Descripción |
---|---|
updateScriptByContent(arrayScriptsNodes) |
Actualiza scripts por contenido |
updateScriptBySrc(matchUrl) |
Actualiza scripts por URL de origen |
Swappit emite un evento personalizado cuando se completa una actualización:
window.addEventListener('mi-handle::update', () => {
console.log('Contenido actualizado');
});
Swappit incluye un sistema de logging con diferentes niveles:
Para activar los logs, inicializa el componente con el parámetro log
en true
:
const app = new Swappit('mi-app', true);
¿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.
Solo necesitas envolver tus enlaces existentes con el componente y automáticamente capturará clics para actualizar contenido sin recargar la página.
Controla el comportamiento con atributos simples: activar logs, precargar contenido o forzar nuevas descargas cuando sea necesario.
Solo acepta rutas relativas internas para garantizar la seguridad y evitar problemas de origen cruzado.
Comparte automáticamente la misma instancia de Swappit entre múltiples botones con el mismo handle, optimizando la memoria y rendimiento.
Esta sección se actualizará sin recargar la página al hacer clic en los botones de abajo.
El contenido se actualizará dependiendo del botón que selecciones.
<!-- 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>
No es necesario escribir JavaScript adicional para utilizar el componente, pero puede interactuar con la instancia de Swappit si lo desea:
// 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");
});
<swappit-button data-handle="mi-app">
<a href="./mi-pagina.html">Ir a Mi Página</a>
</swappit-button>
<a>
con un atributo href
válido./
o /
)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 |
Explora las capacidades de Swappit con estos ejemplos prácticos e interactivos.
Contenido original
// 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('./');
}
<!-- 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>
// 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('./');
}
<!-- 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>
Contenido del header...
Contenido principal...
Contenido del footer...
// 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('./');
}
<!-- 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>
Consulta la documentación completa para aprovechar al máximo Swappit.
Documentación técnica para sacar el máximo provecho de Swappit en tus proyectos.