Omnisearch

Impulsado por la última tecnología Search de Clerk, Omnisearch te proporciona la flexibilidad que necesitas para ofrecer la mejor experiencia de búsqueda moderna:

• Resultados en vivo se muestran a tus visitantes mientras escriben, e incluyen productos, categorías y páginas.
• Ordenación y filtrado: permite a tus visitantes refinar su búsqueda de manera intuitiva y sencilla.
• Fácil de integrar en tu sitio utilizando una de nuestras excelentes plantillas iniciales.
• Se adapta a tu marca cambiando algunos ajustes estándar como logotipo, fuentes, colores y más.
• Es totalmente personalizable con HTML, CSS y Liquid para desarrolladores.

Primeros pasos #

Omnisearch consiste en un Diseño personalizable para los aspectos visuales y un bloque Elemento que permite instalarlo en tu sitio.

Creando un diseño #

Esto se realiza en Search > Designs > New Design

Selecciona el tipo Omnisearch, elige un diseño inicial y asígnale un nombre.

Haz clic en Save para guardar el diseño estándar. Vuelve a la lista de diseños o al diseño principal como un paso de navegación separado.

Nuestros diseños estándar funcionan de inmediato y siempre pueden editarse después. Editar requiere conocimientos de HTML, CSS y Liquid. Consulta Estilización en esta guía para más información.

Creando un Elemento #

Esto se realiza en Search > Element > New Element

Los bloques de Elemento son contenedores para los elementos que creas en tu cuenta de my.clerk.io. Contienen la lógica para mostrar los resultados y la configuración de cuántos resultados mostrar. La lógica de estado vacío también puede manipularse mediante Rules.

• Nombre te ayuda a identificar tu elemento en caso de que quieras crear más de uno. Puede modificarse después.

• Tipo de elemento es Omnisearch por defecto y no debe cambiarse. Aquí también puedes añadir filters si es necesario, pero en la mayoría de los casos esto no es necesario.

• Lógica de estado vacío te permite seleccionar el tipo de productos a mostrar cuando se abre Omnisearch inicialmente, antes de que se escriba nada. Por defecto es Bestsellers, pero también puede personalizarse, por ejemplo, con Visitor Recommendations.

Finalizar Diseño #

El diseño con el que se mostrará el bloque Elemento. Selecciona el diseño creado.

Si tu diseño incluye variables, también puedes configurarlas aquí.

Puedes controlar el número de resultados a mostrar para cada tipo, cada vez que se realiza una búsqueda. Generalmente recomendamos estas cantidades:

• Productos: 20-60
• Sugerencias: 5
• Categorías y páginas: 10

Por último, escoge los atributos que quieres incluir como Facetas y define los nombres con los que se mostrarán en los resultados de búsqueda. Si no puedes encontrar un atributo específico en la lista, agrégalo en la lista de “atributos filtrables”, en Search Configuration.

Insertar en el sitio #

El método recomendado es injection, pero también puedes insertar el elemento en tu sitio con un embedcode.

La visibilidad se utiliza para controlar quién puede ver el Omnisearch.

• En vista previa te permite probar tu elemento sin afectar a tu sitio en vivo. Puedes abrir tu sitio en modo vista previa haciendo clic en “Open site in preview” o agregando ?clerk_content_mode=preview a la url de tu sitio.

• En mi sitio en vivo se utiliza cuando hayas terminado de probar y estés listo para hacerlo público.

Uso de injection #

Esta es la forma más sencilla de instalar. Clerk añadirá automáticamente el código de Omnisearch a tu sitio, dirigiéndose a un campo de búsqueda de tu elección y activándose a partir de un evento.

• Evento controla lo que el usuario debería hacer para activar Omnisearch. Lo más probable es que desees que se muestre cuando tus visitantes hagan clic en el icono de búsqueda o en el campo de entrada.

• Elemento decide la parte del sitio web con la que el usuario debería interactuar. Por ejemplo, si quieres que tu elemento Omnisearch se muestre solo cuando tus visitantes interactúan con la barra de búsqueda (hacen clic o la enfocan), solo necesitas encontrar el CSS selector único aplicado a ella. Si tienes diferentes identificadores en móvil y escritorio, añade ambos.

Para encontrar tu CSS selector único haz lo siguiente:

1. Inspecciona el código de tu sitio. En la mayoría de los navegadores puedes hacer clic derecho en cualquier parte de la página y elegir Inspect o similar.
2. Encuentra el elemento que quieres seleccionar
3. Haz clic derecho sobre él, y busca la opción copiar > copiar selector

Uso de código incrustado #

Esto te permite añadir Omnisearch con un fragmento de código. Para esto necesitas poder editar los archivos HTML de tu tienda online o añadir código desde un editor.

Si tienes cambios sin guardar, guárdalos para generar el código incrustado.

Copia este código y pégalo en el archivo que genera todas las páginas de la tienda, idealmente cerca de la etiqueta </body>.

Reemplaza INSERT_CSS_SELECTOR_FOR_ELEMENT_THAT_SHOULD_TRIGGER_OMNISEARCH por el selector CSS del elemento html que debe activar tu Omnisearch.

A continuación hay un ejemplo completo de un código incrustado de Omnisearch con todas las opciones de configuración:

<span class="clerk"
    data-template="@omnisearch"
    data-api="search/omni"
    data-trigger-element="INSERT_CSS_SELECTOR_FOR_ELEMENT_THAT_SHOULD_TRIGGER_OMNISEARCH"
    data-limit="40"
    data-suggestions="6"
    data-categories="6"
    data-pages="6"
    data-omni-search-suggestions="6"
    data-omni-search-categories="6"
    data-omni-search-pages="6"
    data-omni-search-empty="recommendations/popular">
</span>

Modos de visualización #

Omnisearch soporta dos modos de visualización que controlan cómo aparece la interfaz de búsqueda en tu sitio. Configura esto en la pestaña Insert al editar tu Elemento Omnisearch.

Superposición completa #

Este es el modo por defecto. Al activarse, Omnisearch cubre toda la ventana con una superposición a pantalla completa. La interfaz de búsqueda ocupa la página, entregando una experiencia de búsqueda enfocada.

Usa este modo cuando deseas:

• Un entorno de búsqueda sin distracciones
• Control total sobre el diseño de búsqueda
• Que la interfaz de búsqueda sea completamente independiente del encabezado de tu sitio

Superposición parcial #

Este modo integra Omnisearch con el encabezado existente de tu sitio. En lugar de cubrir toda la pantalla, la superposición de búsqueda aparece debajo de tu encabezado mientras mantiene el encabezado visible y funcional.

Usa este modo si deseas:

• Que el encabezado y la navegación sigan accesibles durante la búsqueda
• Una integración más fluida con el diseño existente de tu sitio
• Que la experiencia de búsqueda se sienta como parte natural de tu sitio

Opciones de configuración #

Cuando se selecciona Superposición Parcial, se habilitan configuraciones adicionales:

Selector de encabezado

El selector CSS del elemento encabezado de tu sitio. Omnisearch utiliza esto para posicionar la superposición justo debajo del encabezado, asegurando una alineación adecuada.

Ejemplos de selectores:

• header
• .site-header
• #main-header

Selector de campo de búsqueda

El selector CSS del campo de entrada de búsqueda existente. Cuando se proporciona, Omnisearch se sincroniza con el campo de búsqueda del encabezado, creando una experiencia unificada donde al escribir en la caja de búsqueda del encabezado se actualizan los resultados de Omnisearch.

Ejemplos de selectores:

• #search-input
• .header-search input
• [name="search"]

Ancho

Controla el tamaño horizontal de la superposición:

• Ancho completo: Ocupa toda la anchura de la ventana
• Ancho de contenido: Coincide con el ancho de un elemento contenedor que especificas con un selector CSS
• Ancho fijo: Un ancho de píxeles específicos que defines

Altura

Controla el tamaño vertical de la superposición:

• Desde el encabezado hasta el fondo: Rellena el espacio desde debajo del encabezado hasta el pie de la ventana
• Porcentaje del viewport: Un porcentaje de la altura de la ventana (ejemplo: 80%)
• Altura fija: Una altura de píxeles específica
• Altura máxima: Establece un límite superior permitiendo que la superposición sea menor si el contenido requiere menos espacio

Alineación horizontal

Controla dónde aparece la superposición horizontalmente:

• Izquierda: Alinea al lado izquierdo de la ventana
• Centro: Centra la superposición horizontalmente
• Derecha: Alinea al lado derecho de la ventana

Posición vertical

Controla la ubicación vertical en relación con el encabezado:

• Debajo del encabezado: Posiciona la superposición directamente debajo del elemento encabezado
• Fijo desde arriba: Un desplazamiento en píxeles específicos desde la parte superior de la ventana

Configuración del diseño #

La mayor parte de Omnisearch puede configurarse cambiando las variables en los archivos de diseño.

En el lenguaje de plantillas liquid, una variable tiene la siguiente estructura:

{% assign variable_name = "variable value" %}

Como regla general, solo se debería cambiar el valor de la variable para configurar Omnisearch.

Los usuarios más técnicos pueden, por supuesto, modificar líneas específicas de HTML y CSS, consulta esta sección.

Logo #

Para añadir un logotipo al diseño de Omnisearch, establece os_brand_logo con la URL de la imagen de tu logotipo.

Carga infinita/automática #

Si deseas controlar si Omnisearch debe cargar más productos automáticamente cuando el usuario llega a la última fila, la variable debe estar en true o false. La variable normalmente se llama os_autoload. Ponla en false para evitar que Omnisearch cargue más resultados automáticamente.

Traducciones #

Por defecto, la plantilla está en inglés. Si tu tienda tiene otro idioma, puedes traducir los textos cambiando los valores de las variables.

Traduce las variables de los botones de ordenación en la plantilla junto con el resto de las variables de texto.

Consejo pro: Utiliza inteligencia artificial generativa (por ejemplo, chatGPT) para traducir en bloque escribiendo “Translate these variable values from English to Danish. Return the full code back so it can be copy/pasted to replace the existing code: PASTE_VARIABLES_HERE”

Estilización #

Para cambiar cualquier aspecto del diseño, la configuración puede hacerse en las variables CSS.

Las plantillas usan variables CSS que tienen una estructura como esta:

--variable_name: variable_value;

Para usuarios más técnicos, pueden modificarse reglas de CSS individuales para cambios complejos de diseño.

Colores #

Los colores personalizables pueden identificarse y configurarse en la sección bajo el comentario “Colors” /* Colors */

Fuentes #

Similar a los colores, la variable de fuente se encuentra bajo el comentario /* Font */.

Normalmente tiene una variable así: --font-family: 'Kumbh Sans', sans serif;

Diseño estándar #

El diseño estándar de Omnisearch incluye:

• Soporte de menú desplegable para variantes: permite a los compradores elegir atributos de variante (ejemplo: talla, color) antes de añadir al carrito.
• Selector de cantidad.
• Botón nativo de “Añadir al carrito” que notifica a Clerk.js, asegurando que la analítica y el merchandising estén sincronizados.
• Maquetado limpio y bien estructurado con comentarios claros.
• Variables centralizadas para estilización y comportamiento, facilitando el ajuste de colores, espacios, etiquetas y opciones comunes sin cambiar el código principal.
• Facet de filtro por precio deslizable para un filtrado rápido por rango.
• Sugerencias clickeables que activan la búsqueda inmediatamente.

Para desarrolladores #

Estilización #

Los diseños consisten en un maquetado principal, estilo CSS y un conjunto de sub-diseños que pueden referenciarse en el maquetado principal.

Puedes editar todo esto por separado para Escritorio y Móvil. Por defecto, Omnisearch usa el mismo HTML para todos los tamaños de pantalla, y usa CSS para ser completamente responsivo. Por esto la pestaña Mobile no tiene código de inicio.

Si lo necesitas, puedes crear un maquetado HTML completamente diferente para móvil, que se usará en pantallas más pequeñas.

Inicialmente, solo podrías querer ajustar algunos detalles para que el diseño coincida con la imagen de tu marca. Siempre podrás editar el diseño más adelante.

HTML #

Este es el maquetado principal que controla la colocación de todos los elementos. Utiliza Liquid como lenguaje de plantillas.

En nuestros diseños iniciales, la primera sección se dedica a los elementos que comúnmente se cambian, como etiquetas de ordenación, moneda y los distintos textos que puedes traducir a tu idioma.

CSS #

Estilo que se inyecta junto con el HTML, dándote control total de lo visual de manera contenida.

Sub-diseños disponibles #

En el editor de código de Search, Available Designs and Components está debajo de la zona principal de código. Desplázate hacia abajo para encontrar y editar un componente. Usa las pestañas sobre el editor para alternar entre el HTML/CSS de escritorio y móvil.

Tras editar un componente, haz clic en Save y luego vuelve al diseño principal por separado. Cualquier sub-diseño añadido aquí puede ser referenciado en el maquetado general. Funcionan como módulos que se editan aparte y se agregan con su ID y nombre: {{@247373 - TopBarSearchForm}}

Puedes borrar, duplicar y copiar la referencia de cualquier sub-diseño haciendo clic en el botón de tres puntos.

Para editar un sub-diseño, haz clic en su icono de Editar. Cuando termines, haz clic en Save & close para volver al editor del diseño principal.

Algunos elementos necesitan identificadores específicos, como:

• El campo de entrada id="clerk-omnisearch-input"
• El contenido envolvente id="clerk-omnisearch-content"

Cada vez que desees comprobar tu progreso, puedes hacerlo haciendo clic en el botón “Preview design”.

Los cambios más habituales en los diseños son estos:

• Logo: accede a TopBarSearchForm y reemplaza el logo por defecto por el tuyo.

• Fuentes: si es necesario, ajusta las fuentes para adecuarlas a la imagen de tu sitio.

• Colores: puedes añadir los colores de tu marca en los elementos que desees destacar o adaptar al resto de tu sitio, como botones y etiquetas.

• Botones y bordes de etiquetas: puedes ajustar su color, radio, ancho…

• Enlaces: si tienes un estilo específico para tus enlaces, también puedes editarlo.

Partes reactivas vs estáticas #

Es importante entender qué partes de Omnisearch se vuelven a renderizar en cada consulta—y cuáles no—al personalizar el diseño.

Partes estáticas se renderizan sólo una vez al abrir la superposición y no se tocan de nuevo en consultas subsiguientes:

• El contenedor de la superposición (clerk-omnisearch-overlay)
• El campo de entrada de búsqueda (#clerk-omnisearch-input)
• Cualquier HTML en el diseño que esté fuera de #clerk-omnisearch-content, como el logo, botón de cerrar o la barra superior

El campo de entrada es intencionadamente estático. Si se renderizara en cada pulsación interrumpiría la escritura del visitante y dañaría la experiencia de búsqueda.

Partes reactivas son todas las que estén dentro de #clerk-omnisearch-content. Esta zona se renderiza de nuevo en cada consulta:

• Resultados de productos
• Facetas y filtros
• Categorías, páginas y sugerencias
• Conteos de resultados y controles de ordenación
• Mensajes de “sin resultados”

Si quieres que un elemento se actualice al cambiar la consulta—por ejemplo, el número de resultados en vivo en el encabezado—debe estar dentro de #clerk-omnisearch-content. Si quieres que se mantenga visible y estable mientras el usuario escribe, ponlo fuera de ese contenedor.

Estado “Sin resultados” #

Cuando una consulta de búsqueda no devuelve productos, Omnisearch no muestra automáticamente un resultado alternativo—esto se controla en el diseño usando Liquid.

El enfoque recomendado es comprobar si products está vacío y condicionalmente mostrar un deslizador alternativo y un mensaje personalizado:

{% if products.length > 0 %}
  <!-- Resultados normales -->
  {% for product in products %}
    <!-- tarjeta de producto -->
  {% endfor %}

{% else %}
  <!-- Alternativa para sin resultados -->
  <div class="clerk-no-results-message">
    Sin resultados para "{{ query }}" — aquí tienes algunas selecciones populares:
  </div>

  <span class="clerk"
    data-api="recommendations/popular"
    data-limit="8"
    data-template="@omnisearch-product-card">
  </span>
{% endif %}

También puedes usar results.products.no_exact_match para detectar cuando Omnisearch muestra resultados aproximados o relacionados en lugar de resultados exactos y mostrar un mensaje apropiado:

{% if results.products.no_exact_match %}
  <div class="clerk-no-exact-match">
    No hay resultados exactos para "{{ query }}" — mostrando coincidencias más cercanas:
  </div>
{% endif %}

Ambos patrones pueden combinarse. Una configuración típica muestra el mensaje no_exact_match sobre los resultados y el deslizador alternativo sólo cuando products.length == 0.

El texto del mensaje de “sin resultados” es HTML plano dentro del diseño, así que puede traducirse o estilizarse libremente sin cambiar nada fuera del editor de diseño.

Estructura de la superposición #

Cuando se inicia Omnisearch se crea un elemento con la clase clerk-omnisearch-overlay y se inyecta al final del body.

Aquí es donde se inyectará el diseño; como el campo de entrada forma parte del diseño, se deben respetar ciertas exigencias estructurales para evitar renderizar de nuevo el input en cada carga. La estructura debería verse así debajo de la superposición:

<div>
    <input type="text" id="clerk-omnisearch-input"/>
    <div id="clerk-omnisearch-content">
        Element!
    </div>
</div>

Campo de entrada #

Para encontrar el campo de entrada debe tener el identificador clerk-omnisearch-input. Una vez activado el elemento, el cursor se moverá a este campo y se agregará la consulta activa para mantener la experiencia de usuario lo más fluida posible.

Contenedor de contenido #

El contenedor de contenido es donde sucede la mayor parte de las cosas; el envoltorio necesita tener el identificador clerk-omnisearch-content. Aquí deben estar las facetas, sliders y todo lo que no sea el campo de entrada.

Clases #

Se puede añadir funcionalidad al diseño agregando clases específicas a los elementos.

Botón de cerrar #

clerk-omnisearch-close

Al asignar esta clase a un elemento del diseño, dicho elemento ocultará la superposición.

Ordenación #

clerk-omnisearch-sort

Encuentra los menús de ordenación y les agrega listeners.

Para tener un elemento de ordenación en el diseño, agrégalo al elemento seleccionador, por ejemplo, un desplegable. Para funcionar, el elemento debe tener el siguiente formato: value:[desc|asc], es decir, el valor que quieres ordenar, dos puntos y “desc” o “asc”. Opcionalmente puedes añadir el atributo data-sort-type si quieres que ordene categorías o páginas.

Faceta de búsqueda #

clerk-facet-search

Si hay una búsqueda de facetas presente, crea un listener y oculta las que no coincidan con la consulta.

La clase, cuando está presente en la web, comprueba la existencia de elementos de búsqueda de faceta. Las búsquedas de faceta permiten que los usuarios busquen dentro de las facetas. Para funcionar, el elemento debe tener un valor de cadena.

Borrado total #

clerk-omnisearch-full-reset

Al hacer clic, los elementos con esta clase borrarán todas las facetas seleccionadas y reiniciarán la consulta.

Borrado de facetas #

clerk-omnisearch-facet-full-reset

Al hacer clic, los elementos con esta clase deseleccionan todas las facetas activas. Normalmente se encuentra en un botón de tipo “Borrar todo” dentro de un grupo de facetas para permitir a los usuarios restablecer todos sus filtros fácilmente.

Borrado de grupo #

clerk-omnisearch-facet-group-reset

Al hacer clic, los elementos con esta clase deseleccionan todos los elementos secundarios dentro del grupo.

Para permitir esta función, un elemento debe tener la clase y el atributo del grupo que deseas borrar, llamado data-facet-group.

Borrado de faceta individual #

clerk-omnisearch-facet-reset

Los elementos con esta clase deben deseleccionar un único elemento usando el par de atributos group/value.

Esta clase está pensada para casos donde es necesario deseleccionar sólo una faceta. El elemento asociado a una faceta debe tener los atributos data-facet-group y data-facet-value. Al activarse, sólo eliminará la faceta correspondiente, dejando las demás sin cambios.

Facet Click #

clerk-facet

Los elementos con esta clase se tratarán como una faceta seleccionable.

Todas las facetas deben tener esta clase junto con los atributos data-facet-group y data-facet-value, para identificar lo que el cliente selecciona.