Carga los recursos solo donde se necesitan

POM expone un registro condicional de recursos para que los componentes puedan solicitar un identificador (handle) o una función conocida del frontend en lugar de cargar todos los estilos y scripts opcionales en cada página. WordPress sigue siendo responsable de la resolución de dependencias, la localización, el código en línea, las traducciones de scripts y la salida HTML final.

Qué deben esperar los propietarios y editores del sitio

La decisión de carga es automática. Un componente de Page Builder, un shortcode, una plantilla de WooCommerce o un plugin compatible declara la función que necesita cuando se renderiza. Las páginas que no usan esa función no solicitan sus archivos.

Algunos ejemplos son Modal, Tooltip, Datepicker, PhotoSwipe, Isotope, el comportamiento de acordeón, los «me gusta» de las entradas, Quick View y Bootstrap ScrollSpy. Las páginas cacheadas sin sesión iniciada y las páginas dinámicas con sesión iniciada usan las mismas declaraciones de funciones.

Los patrones sincronizados y el contenido reutilizable compatible aportan sus propias dependencias, incluso dentro de bloques anidados y vistas previas de páginas autorizadas. No necesitas añadir un bloque Conditional Asset junto a un patrón. Las referencias repetidas comparten una única solicitud de recurso; siguen aplicándose los requisitos de publicación del origen y de permisos. Guarda el contenido de origen reutilizable antes de revisar la vista previa de una página que lo consume.

Solicita manualmente un recurso aprobado en Gutenberg

Usa Conditional Asset solo cuando un marcado personalizado revisado necesita un recurso que el descubrimiento normal de componentes todavía no solicita. Los bloques ordinarios de POM declaran sus propias dependencias; no es necesario añadir esta utilidad junto a cada bloque.

Debes ser administrador del sitio o superadministrador de la red. Abre Pages → All Pages → Edit, o el editor de la entrada correspondiente, y:

1. Inserta Conditional Asset, en la raíz del documento o dentro de un contenedor de contenido POM compatible.
2. Abre el panel Conditional asset de la barra lateral del bloque y busca Approved resource. Prefiere una función integrada completa, como Tabs, antes que un identificador individual de script o estilo. Un handle es el nombre registrado que WordPress usa para identificar un recurso, no su URL.
3. Revisa Requested handles y cualquier Direct dependencies. El catálogo procede del registro condicional actual, no de todos los scripts de plugins registrados en WordPress.
4. Opcionalmente, abre Organization y establece un Administrative name para identificar la solicitud en la Vista de lista.
5. Guarda la página, obtén una vista previa y verifica el comportamiento previsto y las solicitudes de recursos antes de publicar.

La barra de herramientas flotante ofrece Choose a built-in feature y Refresh asset availability. El botón Refresh availability de la barra lateral recarga el catálogo actual sin ejecutar el recurso. Selecciona No asset, o usa el control de restablecimiento del campo de recurso, para borrar la solicitud.

La tarjeta del lienzo es solo un marcador del editor. Este bloque dinámico almacena únicamente su identidad de recurso y sus metadatos administrativos. No produce ningún elemento visible, contenedor, clase CSS, estilo en línea ni carga ejecutable en el frontend. Los estilos y scripts se cargan a través del descubrimiento existente del tema y del sistema de dependencias de WordPress. Siguen aplicándose su posición de carga normal, sus ajustes en vivo, el contexto de la página y las reglas de consentimiento. La sola disponibilidad en el registro no garantiza que un recurso se ejecute en una página concreta.

Una solicitud ya configurada puede permanecer mientras un usuario que no es administrador edita el contenido circundante, lo mueve o lo elimina. Añadir, duplicar o cambiar solicitudes requiere un administrador, incluso al usar la edición de código o REST. Las importaciones nativas que no son REST también deben ejecutarse como administrador; una inserción nativa rechazada devuelve un error sin guardar el contenido enviado. Las selecciones de recursos no admiten enlaces de datos dinámicos. La creación de patrones sincronizados a partir de esta utilidad está deshabilitada; usa una solicitud explícita en el documento o plantilla que posee la función.

No se aceptan URLs, rutas del sistema de archivos, JavaScript en línea, handles arbitrarios de WordPress ni scripts personalizados propiedad de los ajustes. El web_script shortcode conservado sigue admitiendo su comportamiento establecido de scripts personalizados; este bloque no lo convierte ni lo reescribe. Los identificadores de estilo individuales son una comodidad adicional, no un control de posición para scripts en línea.

Verifica o soluciona una solicitud manual

• Si una identidad ya no está en el catálogo, permanece visible para su reparación pero no se carga. Pide a un administrador que la sustituya o la borre.
• Una función cuyas dependencias registradas faltan no se carga. Restaura la integración que registró esas dependencias o selecciona una función disponible.
• Si un recurso aparece en la lista pero el comportamiento está ausente, comprueba el ajuste correspondiente del tema, el marcado requerido, el contexto de la página y el consentimiento. Actualizar el catálogo no habilita una integración.
• Confirma que hay una sola solicitud de recurso compartida, sin ejecución duplicada y sin recursos adicionales en una página comparable que carece de la utilidad o del componente correspondiente.
• Guarda/recarga el editor para verificar la selección y el nombre administrativo. El bloque no añade espaciado en la página pública.
• El contenido que contiene esta utilidad se revisa dentro de un límite de 8 MiB, 5.000 bloques, 64 niveles y 128 utilidades. Divide una composición inusualmente grande en páginas gestionadas de forma independiente antes de añadir más solicitudes.

Asistentes públicos

Usa una función cuando el componente necesite un grupo completo de scripts y estilos:

if (function_exists('pom_require_front_asset_feature')) {
    pom_require_front_asset_feature('modal');
}

Solo se aceptan handles y funciones registrados. Los slugs de funciones integradas son jarallax, photoswipe, isotope, datepicker, tooltip, modal, collapse, tabs, accordion, scrollspy, feed_fullpage, share, page_nav, author_page, rating, advanced_filters, social_icons, woocommerce_product_modal, woocommerce_quick_view, request_info_popup, form_controls, header_sign_form, post_display_rules y post_likes.

Registra un recurso de integración

Un plugin o un tema hijo puede ampliar el registro y el mapa de funciones. Registra ambos filtros antes de wp_enqueue_scripts; POM normaliza y reutiliza una única instantánea durante el resto de la solicitud.

add_filter(
    'pom_conditional_front_asset_registry',
    static function (array $registry): array {
        $registry['styles']['example-panel-style'] = array(
            'uri'   => plugins_url('assets/panel.css', __FILE__),
            'deps'  => array(),
            'media' => 'all',
        );

        $registry['scripts']['example-panel-script'] = array(
            'uri'      => plugins_url('assets/panel.js', __FILE__),
            'deps'     => array('web-theme-js'),
            'footer'   => true,
            'strategy' => 'defer',
        );

        return $registry;
    }
);

add_filter(
    'pom_conditional_front_asset_feature_map',
    static function (array $features): array {
        $features['example_panel'] = array('example-panel-style', 'example-panel-script');

        return $features;
    }
);

Usa handles distintos para los recursos de script y de hoja de estilos por separado. Un handle no debe aparecer en ambas secciones del registro.

El encolado tradicional de WordPress sigue siendo compatible. Después de que POM registre un handle, un plugin puede llamar a wp_enqueue_script() o wp_enqueue_style() directamente. No crees un segundo cargador de dependencias en el navegador para estos handles.

Elige metadatos de entrega seguros

Los estilos que controlan la geometría, la visibilidad, el diseño responsivo o la apariencia inicial deben usar la entrega normal de hojas de estilos. Esto incluye controles de formulario visibles, calendarios en línea, la estructura Modal y otros CSS de componentes que provocarían un destello o un desplazamiento del diseño si llegaran tarde.

Una hoja de estilos puede declarar load_strategy => 'preload' solo cuando no pueda cambiar el estado visual inicial. POM emite entonces el marcado preload/onload y una alternativa de hoja de estilos noscript. fetchpriority puede ser high, low, auto o vacío.

Un script puede declarar strategy => 'defer' o strategy => 'async' de WordPress. Ten en cuenta el orden de las dependencias: usa async solo para un recurso que sea verdaderamente independiente.

$registry['styles']['example-enhancement'] = array(
    'uri'           => plugins_url('assets/enhancement.css', __FILE__),
    'load_strategy' => 'preload',
    'fetchpriority' => 'low',
    'media'         => 'all',
);

Si un renderizador solicita una hoja de estilos después de que el head ya se haya impreso, POM la imprime una vez en el pie de página con sus dependencias de WordPress. Esta es una alternativa de compatibilidad, no un sustituto de declarar los requisitos de los componentes visibles durante el descubrimiento.

Carga de PhotoSwipe

PhotoSwipe es la excepción intencional al encolado directo en tiempo de ejecución. Una página con una galería POM ampliable carga un pequeño cargador específico de la función. Ese cargador comienza a descargar el CSS y el JavaScript de PhotoSwipe al pulsar el puntero o al recibir el foco del teclado, y reutiliza la misma Promise cuando se abre la imagen. El tiempo de ejecución completo de PhotoSwipe no se carga en páginas sin una galería compatible.

Este comportamiento pertenece al propio cargador de PhotoSwipe. No expone ni requiere una API de recursos de interacción de propósito general.

Datepicker y Tooltip tras la inserción AJAX

Las páginas que pueden renderizar inicialmente o insertar después marcado de Datepicker o Tooltip deben requerir la función correspondiente en el documento padre. Una respuesta AJAX no puede añadir una hoja de estilos a un head que el navegador ya ha recibido.

Después de insertar el marcado compatible, emite pom:ajaxComplete con el contenedor insertado reducido:

document.dispatchEvent(new CustomEvent('pom:ajaxComplete', {
    detail: {
        container: insertedContainer,
        scope: insertedContainer,
        source: 'example_results'
    }
}));

Los tiempos de ejecución condicionales de Datepicker y Tooltip inicializan solo ese ámbito e ignoran los elementos que ya estaban inicializados. Los datepickers en línea visibles reservan su geometría esperada en la hoja de estilos principal para reducir el movimiento del diseño mientras el tiempo de ejecución se inicializa.

Añade ScrollSpy a una plantilla o archivo

Bootstrap ScrollSpy no forma parte de theme.min.js. Requiérelo solo en un documento que contenga la navegación y el contenedor de desplazamiento coincidentes:

if (function_exists('pom_require_front_asset_feature')) {
    pom_require_front_asset_feature('scrollspy');
}

El handle web-bootstrap-scrollspy depende de web-bootstrap-util. Util ya vive en el paquete compartido del tema, por lo que esta dependencia no descarga otra copia. Un plugin también puede encolar web-bootstrap-scrollspy a través de la API tradicional de WordPress.

Sigue usando data-spy="scroll", data-target y el contrato de enlaces de navegación de Bootstrap. POMScrollSpy.init(scope, config) inicializa un documento o un ámbito insertado, POMScrollSpy.refresh(scope) recalcula las instancias existentes tras los cambios de diseño, y POMScrollSpy.dispose(scope) elimina sus escuchadores.

La navegación de categorías de Fenómenus posee su propio comportamiento independiente de navegación por archivo y no requiere esta función de Bootstrap.

Abre un modal integrado

Requiere la función Modal en PHP y mantén los atributos de datos estándar de Bootstrap:

if (function_exists('pom_require_front_asset_feature')) {
    pom_require_front_asset_feature('modal');
}

<button type="button" data-toggle="modal" data-target="#example-modal">
    Open
</button>

<div id="example-modal" class="modal" tabindex="-1" role="dialog" aria-hidden="true">
    <div class="modal-dialog" role="document">
        <div class="modal-content">...</div>
    </div>
</div>

POM encola condicionalmente la hoja de estilos de Modal y el comportamiento de Bootstrap en el documento inicial. Los comportamientos automáticos, diferidos, programados, de retorno por tabulación, de apertura única, de fondo, de Escape, de foco, de cierre y programáticos de Bootstrap siguen estando disponibles. Los elementos no nativos que usan role="button" conservan la activación con Enter y Espacio a través de la API de datos condicional de Modal.

Descubrimiento, almacenamiento en caché y regeneración

POM puede crear manifiestos de descubrimiento por entrada y por solicitud a partir del contenido del constructor y de las plantillas. Un renderizador debe seguir llamando al asistente de recursos correspondiente como alternativa, porque los datos de descubrimiento guardados pueden estar obsoletos o una plantilla puede renderizarse de forma condicional.

El Custom HTML nativo se inspecciona como marcado. Las cargas vc_raw_html encerradas se decodifican y filtran antes de que los mismos detectores de marcado las inspeccionen, incluso cuando están anidadas dentro de otros shortcodes. Esto no renderiza el contenido, no ejecuta filtros personalizados ni interpreta instrucciones codificadas de shortcode/bloque. El HTML simple no solicita recursos opcionales; el código arbitrario de terceros sigue necesitando una integración registrada explícita.

La expansión heredada de HTML sin procesar está limitada a 256 fragmentos y 4 MiB de código codificado combinado por cadena de contenido analizada. Una advertencia de descubrimiento informa de una inspección incompleta; el código guardado nunca se trunca. Divide los códigos inusualmente grandes en componentes mantenibles o declara explícitamente sus dependencias mediante los asistentes compatibles.

Después de una actualización que cambie las reglas de descubrimiento, regenera los datos de descubrimiento existentes y borra la caché de páginas. Guardar una página afectada actualiza sus propios datos. Los administradores del sitio con WP-CLI pueden inspeccionar primero y luego aplicar una reconstrucción del sitio actual:

wp pom rebuild-asset-discovery --scope=all --dry-run
wp pom rebuild-asset-discovery --scope=all

Usa --url=<site-url> para dirigirte a un sitio multisitio concreto. Una reconstrucción actualiza la información de recursos derivada, no el contenido creado de páginas o shortcodes. Revisa las advertencias antes de confiar en el resultado.

La caché de POM puede almacenar las etiquetas finales como cualquier otra parte del HTML estático. El registro de recursos no contiene ningún estado específico del visitante. Las respuestas personalizadas de cuenta, carrito, pago, controladas por permisos y otras respuestas dinámicas mantienen sus límites de caché normales.

Cuando cambie un recurso de tema compilado, reconstruye los recursos del tema, regenera los recursos del sitio afectados y purga las cachés de página/CDN pertinentes como parte del proceso normal de publicación. No despliegues archivos compilados modificados bajo una versión pública del tema sin cambios.

Verificación

Para cada integración condicional:

1. Verifica que la página que contiene el componente solicita cada handle requerido una sola vez.
2. Verifica que una página sin el componente no solicita esos handles.
3. Prueba las solicitudes cacheadas sin sesión y las dinámicas con sesión.
4. Prueba el comportamiento del teclado y cualquier alternativa sin JavaScript que la acción requiera.
5. Para resultados dinámicos, inserta el fragmento, emite el evento de finalización con ámbito y verifica que los componentes existentes no se inicializan dos veces.
6. Comprueba por separado el comportamiento automático de Modal y del Datepicker en línea visible, ya que ninguno de los dos puede esperar a la interacción del usuario.