JNP Biblioteca de Videos

Plugin para WordPress que permite administrar y mostrar una galería de videos desde YouTube, proveedores compatibles con oEmbed, archivos de video directos o URLs embebibles mediante iframe.

Incluye un diseño responsive de 2 o 3 columnas, buscador por título y sincronización de la búsqueda con la query string de la URL.

Características

• Tipo de contenido independiente para administrar videos desde WordPress.
• Compatible con enlaces de YouTube.
• Compatible con Vimeo y otros proveedores soportados por oEmbed de WordPress.
• Compatible con archivos directos:
  • MP4
  • M4V
  • WebM
  • OGV
  • OGG
  • MOV
• Modo de respaldo mediante iframe para URLs que permitan contenido embebido.
• Selector global de 2 o 3 columnas.
• Configuración individual mediante shortcode.
• Diseño responsive para escritorio, tablet y dispositivos móviles.
• Buscador dinámico por título.
• Búsqueda sin distinguir mayúsculas, minúsculas o acentos.
• Actualización de la query string sin recargar la página.
• Lectura automática del término de búsqueda desde la URL.
• Imagen destacada como portada de archivos de video directos.
• Carga diferida de iframes mediante loading="lazy".
• Caché temporal para resultados oEmbed.
• Sin dependencias externas ni plugins de pago.

Requisitos

• WordPress 6.0 o superior.
• PHP 7.4 o superior.

Instalación

Desde un archivo ZIP

1. Descarga el archivo ZIP del plugin.
2. En WordPress, entra en Plugins → Añadir plugin.
3. Presiona Subir plugin.
4. Selecciona el archivo jnp-video-library.zip.
5. Presiona Instalar ahora.
6. Activa JNP Biblioteca de Videos.

Instalación manual

1. Copia la carpeta jnp-video-library dentro de:

/wp-content/plugins/

2. Entra en Plugins desde el escritorio de WordPress.
3. Activa JNP Biblioteca de Videos.

Agregar un video

1. En el panel de WordPress, entra en Galería de videos → Añadir nuevo.
2. Escribe el título del video.
3. Opcionalmente, agrega una descripción en el editor.
4. Pega la URL en el campo URL del video.
5. Selecciona el tipo de reproducción.
6. Agrega una imagen destacada si utilizarás un archivo de video directo y deseas mostrar una portada.
7. Publica el video.

Tipos de reproducción

Automático

Es la opción recomendada.

El plugin intenta procesar la URL en este orden:

1. Detecta si es un archivo de video directo.
2. Solicita el contenido mediante oEmbed de WordPress.
3. Utiliza un iframe como respaldo.

Archivo de video directo

Utiliza el reproductor HTML5 nativo de WordPress. Está pensado para URLs que apuntan directamente a archivos como .mp4, .webm u .ogv.

Forzar iframe

Muestra la URL dentro de un iframe. El sitio de origen debe permitir que su contenido sea cargado desde otros dominios.

Algunas páginas bloquean el uso de iframe mediante encabezados como X-Frame-Options o políticas CSP. En esos casos, el contenido no podrá mostrarse aunque la URL sea válida.

Insertar la galería

Agrega el siguiente shortcode en una página, entrada o bloque de shortcode:

[jnp_video_gallery]

Ejemplos de shortcode

Galería con dos columnas

[jnp_video_gallery columns="2"]

Galería con tres columnas

[jnp_video_gallery columns="3"]

Galería sin buscador

[jnp_video_gallery columns="3" search="no"]

Parámetro personalizado para la búsqueda

[jnp_video_gallery query_key="buscar_video"]

La URL podría verse así:

https://tusitio.com/videos/?buscar_video=wordpress

Placeholder personalizado

[jnp_video_gallery placeholder="Buscar tutorial..."]

Ordenar alfabéticamente

[jnp_video_gallery orderby="title" order="ASC"]

Limitar la cantidad de videos

[jnp_video_gallery limit="6"]

Configuración completa

[jnp_video_gallery columns="3" search="yes" query_key="video_busqueda" placeholder="Buscar video..." limit="12" orderby="title" order="ASC"]

Parámetros disponibles

Parámetro	Valores	Predeterminado	Descripción
columns	2, 3	3	Número de columnas en escritorio.
search	yes, no	yes	Muestra u oculta el buscador.
query_key	Texto válido para URL	video_busqueda	Nombre del parámetro utilizado en la query string.
placeholder	Texto	Buscar video por título…	Texto mostrado dentro del buscador.
limit	Número entero o -1	-1	Cantidad máxima de videos. -1 muestra todos.
orderby	date, title, menu_order, rand	date	Criterio utilizado para ordenar los videos.
order	ASC, DESC	DESC	Dirección del orden.

Búsqueda mediante query string

El buscador puede recibir automáticamente el término desde la URL.

Con la configuración predeterminada:

https://tusitio.com/videos/?video_busqueda=woocommerce

Al abrir esa URL:

1. El campo de búsqueda se completa con woocommerce.
2. La galería muestra únicamente los videos cuyo título contiene ese término.
3. Al modificar el buscador, la URL se actualiza mediante history.replaceState sin recargar la página.

La búsqueda se realiza en el navegador sobre los videos cargados por el shortcode. Por esta razón, el parámetro limit también define cuántos videos estarán disponibles para filtrar.

Configuración global

Entra en:

Galería de videos → Ajustes

Desde esta pantalla puedes configurar:

• Número predeterminado de columnas.
• Nombre predeterminado del parámetro de búsqueda.
• Texto predeterminado del buscador.

Los atributos enviados directamente al shortcode tienen prioridad sobre la configuración global.

Diseño responsive

El comportamiento predeterminado es:

• Escritorio: 2 o 3 columnas, según la configuración.
• Pantallas menores de 1024 px: una galería de 3 columnas pasa a 2 columnas.
• Pantallas menores de 700 px: la galería pasa a una columna.

Compatibilidad de URLs

YouTube

Ejemplo:

https://www.youtube.com/watch?v=VIDEO_ID

También funciona con URLs compatibles con el sistema oEmbed de WordPress.

Video directo

Ejemplo:

https://tusitio.com/wp-content/uploads/2026/07/video.mp4

URL embebible

Puede utilizarse una URL de un reproductor externo siempre que el proveedor permita mostrarla dentro de un iframe.

Estructura del plugin

jnp-video-library/
├── assets/
│   ├── css/
│   │   └── frontend.css
│   └── js/
│       └── frontend.js
├── jnp-video-library.php
├── readme.txt
└── README.md

Funcionamiento técnico

El plugin registra el Custom Post Type privado jnp_video, visible únicamente en el panel administrativo.

Cada video guarda los siguientes metadatos:

• _jnp_video_url: URL del contenido.
• _jnp_video_source: estrategia de reproducción seleccionada.

La galería se genera mediante WP_Query y el shortcode:

[jnp_video_gallery]

Para optimizar el rendimiento, los resultados oEmbed válidos se almacenan temporalmente durante 12 horas. Los intentos fallidos se almacenan durante una hora para evitar solicitudes externas repetitivas.

Seguridad

El plugin aplica prácticas nativas de WordPress:

• Verificación mediante nonce al guardar datos.
• Comprobación de permisos con current_user_can().
• Sanitización de URLs con esc_url_raw().
• Sanitización de textos y parámetros.
• Escape de atributos y contenido antes de renderizar.
• Lista permitida para tipos de fuente y parámetros de ordenamiento.
• Bloqueo de acceso directo al archivo principal mediante ABSPATH.

Personalización visual

Los estilos públicos se encuentran en:

assets/css/frontend.css

Clases principales disponibles:

.jnp-video-gallery {}
.jnp-video-gallery__search {}
.jnp-video-gallery__search-input {}
.jnp-video-gallery__grid {}
.jnp-video-card {}
.jnp-video-card__media {}
.jnp-video-card__content {}
.jnp-video-card__title {}
.jnp-video-card__description {}

Puedes sobrescribir estas clases desde el tema hijo o desde el personalizador de WordPress.

Ejemplo:

.jnp-video-card {
  border-radius: 20px;
}

.jnp-video-card__title {
  font-size: 1.35rem;
}

Preguntas frecuentes

¿Puedo mostrar videos de cualquier sitio web?

No necesariamente. El plugin puede intentar mostrar una URL mediante oEmbed, video HTML5 o iframe, pero el proveedor debe permitir la reproducción externa.

¿El buscador recarga la página?

No. El filtrado ocurre en el navegador y la query string se actualiza sin recargar la página.

¿La búsqueda distingue acentos?

No. Una búsqueda como programacion puede encontrar un título como Programación.

¿Puedo colocar varias galerías en una misma página?

Sí. Cada galería se inicializa de manera independiente. Se recomienda utilizar un query_key diferente para cada galería cuando necesites mantener búsquedas independientes en la URL.

Ejemplo:

[jnp_video_gallery query_key="tutoriales"]
[jnp_video_gallery query_key="entrevistas"]

¿Puedo usar una imagen de portada?

Sí. Para archivos directos, establece una imagen destacada. El plugin la utilizará como atributo poster del reproductor HTML5.

¿Por qué una URL funciona al abrirla directamente pero no dentro de la galería?

Probablemente el servidor de origen bloquea su visualización dentro de un iframe. En ese caso debes utilizar una URL oficial de inserción, un proveedor compatible con oEmbed o un archivo directo.

Desarrollo local

1. Clona el repositorio dentro de wp-content/plugins:

git clone URL_DEL_REPOSITORIO jnp-video-library

2. Activa el plugin desde WordPress.
3. Crea algunos videos de prueba.
4. Inserta el shortcode en una página.

Roadmap

Posibles mejoras para próximas versiones:

• Categorías y etiquetas para videos.
• Filtros por categoría.
• Paginación o botón “Cargar más”.
• Vista modal o lightbox.
• Bloque nativo para Gutenberg.
• Importación masiva mediante CSV.
• Miniaturas automáticas de YouTube.
• Configuración de colores y separación desde el administrador.
• Compatibilidad con Elementor y WPBakery mediante widgets propios.

Registro de cambios

1.0.0

• Primera versión pública.
• Administración mediante Custom Post Type.
• Compatibilidad con YouTube y oEmbed.
• Reproducción de archivos directos.
• Respaldo mediante iframe.
• Diseño de 2 o 3 columnas.
• Buscador por título.
• Sincronización con query string.
• Configuración global y atributos de shortcode.

Autor

Jhorman Nieto P

• Sitio web: jhorman.com

Licencia

Este proyecto está disponible bajo la licencia GPL-2.0-or-later.