Omnisearch

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

• Los resultados en vivo se muestran a tus visitantes mientras escriben, e incluyen productos, categorías y páginas.
• Ordenación y filtrado: para que tus visitantes puedan refinar su búsqueda de forma intuitiva y sencilla.
• Fácil de integrar en tu sitio utilizando una de nuestras excelentes plantillas de inicio.
• Se adapta a tu marca a través de unos pocos ajustes estándar como logo, fuentes, colores y más.
• Es completamente personalizable con HTML, CSS y Liquid para desarrolladores.

Primeros pasos #

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

Crear un diseño #

Esto se realiza en Search > Designs > New Design

Selecciona el tipo Omnisearch, elige un diseño inicial y ponle un nombre.

Haz clic en Save & Close para finalizar el diseño estándar.

Nuestros diseños estándar funcionan directamente y siempre se pueden editar más tarde. La edición requiere conocimientos de HTML, CSS y Liquid. Consulta Estilizado en esta guía para más información.

Crear un Elemento #

Esto se realiza en Search > Element > New Element

Los bloques de Elementos son contenedores para los elementos que crees en tu cuenta de my.clerk.io. Contienen la lógica para mostrar resultados y configuraciones sobre cuántos resultados mostrar. La lógica del estado vacío también puede ser manipulada mediante Reglas.

• Nombre te ayuda a identificar tu elemento en caso de que quieras crear más de uno. Puede ser modificado posteriormente.

• Tipo de Elemento es Omnisearch por defecto y no debe ser cambiado. Aquí también puedes agregar filtros si es necesario, pero para la mayoría de las configuraciones esto no es necesario.

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

Finalizar Diseño #

El diseño para renderizar el bloque Elemento. Selecciona el diseño que creaste.

Si tu diseño incluye variables, también pueden establecerse aquí.

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

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

Por último, elige los atributos que quieres incluir como Facetas y establece los nombres con los que se mostrarán en los resultados de búsqueda. Si no encuentras un atributo específico en la lista, agrégalo en la lista de “filterable attributes”, en Configuración de Search.

Insertar en el sitio #

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

La Visibilidad se usa para controlar quién puede ver el Omnisearch.

• En vista previa te permite probar tu elemento sin afectar 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 usa cuando has terminado de probar y estás listo para hacerlo público.

Usando inyección #

Esta es la forma más sencilla de instalar. Clerk añadirá automáticamente el código de Omnisearch a tu sitio, al orientar un campo de búsqueda elegido por ti y activarlo basándose en un evento.

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

• Elemento decide la parte del sitio web que debe ser interactuada por el usuario. Por ejemplo, si quieres que tu elemento Omnisearch se muestre solo cuando tus visitantes interactúan con tu barra de búsqueda (clic o enfoque), solo tienes que encontrar el selector CSS único que se le aplica. Si tienes identificadores diferentes en móvil y escritorio, añade ambos.

Encuentra tu selector CSS único de esta forma:

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

Usando código embebido #

Esto permite agregar Omnisearch con un fragmento de código. Usar esto requiere que puedas editar los archivos HTML de tu tienda online o agregar código con un editor.

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

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

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

A continuación, un ejemplo completo de un embed code 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 admite dos modos de visualización que controlan cómo aparece la interfaz de búsqueda en tu sitio. Configúralo en la pestaña Insert al editar tu Elemento Omnisearch.

Superposición completa #

Este es el modo predeterminado. Cuando se activa, Omnisearch cubre toda la ventana del navegador con una superposición de pantalla completa. La interfaz de búsqueda ocupa toda la página, proporcionando una experiencia de búsqueda enfocada.

Usa este modo cuando quieras:

• 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 de la cabecera de tu sitio

Superposición parcial #

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

Usa este modo cuando quieras:

• Que la cabecera y navegación sigan siendo 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 seleccionas Superposición Parcial, aparecen ajustes adicionales:

Selector de cabecera

El selector CSS del elemento de cabecera de tu sitio. Omnisearch lo usa para posicionar la superposición directamente debajo tu cabecera, asegurando la alineación adecuada.

Selectores ejemplo:

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

Selector de entrada de búsqueda

El selector CSS del campo de búsqueda existente. Si se proporciona, Omnisearch se sincroniza con el campo de búsqueda de la cabecera, creando una experiencia unificada donde lo que escribas en la caja de búsqueda de la cabecera actualiza los resultados de Omnisearch.

Selectores ejemplo:

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

Ancho

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

• Ancho completo: Abarca todo el ancho de la ventana
• Ancho de contenido: Coincide con el ancho de un elemento contenedor que especifiques con un selector CSS
• Ancho fijo: Un ancho en píxeles específico que defines

Alto

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

• Desde la cabecera hasta abajo: Llena el espacio desde debajo de la cabecera hasta el fondo de la ventana
• Porcentaje de ventana: Un porcentaje del alto de la ventana (por ej., 80%)
• Alto fijo: Un alto en píxeles específico
• Alto máximo: Establece un límite superior permitiendo que la superposición sea más pequeña si el contenido requiere menos espacio

Alineación horizontal

Controla dónde aparece la superposición horizontalmente:

• Izquierda: Alinea a la izquierda de la ventana
• Centro: Centra la superposición horizontalmente
• Derecha: Alinea a la derecha de la ventana

Posición vertical

Controla la colocación vertical respecto a la cabecera:

• Debajo de la cabecera: Posiciona la superposición justo bajo la cabecera
• Fijo desde arriba: Un desplazamiento en píxeles desde la parte superior de la ventana

Configuración de diseño #

La mayoría de Omnisearch puede configurarse cambiando las variables que están 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 debe cambiarse el valor de la variable para configurar Omnisearch.

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

Logo #

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

Carga infinita/automática #

Si quieres controlar si Omnisearch debe cargar más productos automáticamente, una vez que el usuario ha hecho scroll hasta la última fila de productos, la variable debe establecerse a true o false. La variable normalmente se llama os_autoload. Establécela 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 también las variables de los botones de ordenación en la plantilla junto con el resto de variables de texto.

Protip: Usa IA generativa (por ejemplo chatGPT) para traducir varias variables a la vez escribiendo “Traduce estos valores de variables de inglés a danés. Devuelve el código completo para poder copiar/pegar y reemplazar el existente: PASTE_VARIABLES_HERE”

Estilizado #

Para cambiar cualquier aspecto visual, la configuración puede hacerse mediante variables de CSS.

Las plantillas usan variables de CSS que tienen la siguiente estructura:

--variable_name: variable_value;

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

Colores #

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

Fuentes #

De forma similar a los colores, la variable de fuente puede encontrarse bajo el comentario /* Font */.

Normalmente tendrá una variable como: --font-family: 'Kumbh Sans', sans serif;

Diseño estándar #

El diseño estándar para Omnisearch incluye:

• Soporte para menú desplegable de variantes: Permite al comprador elegir atributos de variante (por 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 analytics y merchandising permanezcan sincronizados.

• Marcado limpio y bien estructurado con comentarios claros.

• Variables centralizadas para estilo y comportamiento, facilitando la edición de colores, espaciados, etiquetas y opciones comunes sin modificar el código central.

• Faceta de deslizador de precio para filtrar por rango fácilmente.

• Sugerencias clicables que disparan una búsqueda de inmediato.

Para desarrolladores #

Estilizado #

Los diseños constan de un layout principal, estilos CSS y un conjunto de subdiseños que pueden referenciarse en el layout principal.

Puedes editar todo esto tanto para escritorio como móvil por separado. Por defecto, Omnisearch utiliza el mismo HTML para todos los tamaños de pantalla y usa CSS para ser totalmente responsivo. Por eso la pestaña de móvil empieza sin código.

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

Inicialmente, quizá solo quieres ajustar unas pocas cosas para que el diseño coincida con el aspecto y sensación de tu marca. Siempre podrás editar tu diseño más adelante.

HTML #

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

En nuestros diseños iniciales, la primera sección está dedicada a los elementos más comúnmente modificados, como etiquetas de ordenación, moneda y varios textos que puedes traducir a tu idioma.

CSS #

Estilos que se inyectan junto al HTML, dándote control absoluto sobre los aspectos visuales de forma contenida.

Subdiseños disponibles #

Cualquier diseño añadido aquí puede referenciarse en el layout general. Funcionan como módulos que se editan por separado y se agregan mediante su ID y nombre: {{@247373 - TopBarSearchForm}}

Puedes eliminar, duplicar y copiar la referencia de cualquier subdiseño haciendo clic en el botón de tres puntos.

Para editar un subdiseño, haz clic en su icono Editar. Una vez que termines de editar, haz clic en Guardar y cerrar para volver al editor de layout principal.

Algunos elementos requieren identificadores específicos, como por ejemplo:

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

Siempre que quieras ver tu progreso, puedes hacerlo pulsando el botón “Vista previa del diseño”.

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

• Logo: Accede a TopBarSearchForm y cambia el logo por el tuyo.

• Fuentes: Si lo necesitas, ajusta las fuentes para adecuarlas a tu marca.

• Colores: Puedes añadir los colores de tu marca en los elementos que quieras resaltar o armonizar con el resto de tu sitio como botones y etiquetas.

• Botones y bordes de etiquetas: Puedes ajustar sus colores, radius, ancho, etc.

• Links: Si tienes un estilo específico para los enlaces, también puedes editarlo.

Partes reactivas vs estáticas #

Entender qué partes de Omnisearch se vuelven a renderizar por búsqueda—y cuáles no—es importante al personalizar el diseño.

Partes estáticas se renderizan una vez cuando la superposición se abre y no se modifican en búsquedas subsiguientes:

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

El campo de entrada es intencionadamente estático. Renderizarlo en cada pulsación interrumpiría la escritura del visitante y rompería la experiencia de búsqueda.

Partes reactivas son todo lo que está dentro de #clerk-omnisearch-content. Todo este wrapper se vuelve a renderizar tras cada búsqueda:

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

Si quieres que un elemento se actualice cuando cambie la búsqueda—por ejemplo un contador de resultados en vivo en la cabecera—debe estar dentro de #clerk-omnisearch-content. Si quieres que se quede visible y estable mientras el visitante escribe, colócalo fuera de ese wrapper.

Estado sin resultados #

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

El enfoque recomendado es comprobar si los productos están vacíos y renderizar condicionalmente un slider de productos y un mensaje personalizado:

{% if products.length > 0 %}
  <!-- Normal results -->
  {% for product in products %}
    <!-- product card -->
  {% endfor %}

{% else %}
  <!-- No results fallback -->
  <div class="clerk-no-results-message">
    No hay resultados para "{{ query }}" — aquí tienes algunas recomendaciones 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 está mostrando coincidencias aproximadas en vez de resultados exactos y mostrar el mensaje adecuado:

{% 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 en línea sobre los resultados y el slider solo cuando products.length == 0.

El texto de “sin resultados” es HTML plano dentro del diseño, así que puedes traducirlo o estilizarlo libremente sin cambiar ninguna configuración 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í se inyectará el diseño; ya que el campo de entrada forma parte, necesitamos unas exigencias estructurales para asegurarnos de que no se re-renderiza el campo de entrada en cada carga. La estructura debe 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 reconocer el campo de entrada debe tener el identificador clerk-omnisearch-input. Una vez que el elemento disparador ha sido activado, pasamos el foco del cursor a ese elemento y le añadimos la consulta, para mantener la experiencia de usuario lo más fluida posible.

Wrapper de contenido #

El wrapper de contenido es donde acontecen la mayoría de cosas; el contenedor a su alrededor debe tener el identificador clerk-omnisearch-content. Aquí deben ir facetas, sliders y todo excepto el campo de entrada.

Clases #

Puedes añadir funcionalidad al diseño agregando clases específicas a elementos.

Botón de cierre #

clerk-omnisearch-close

Si le añades esta clase a un elemento del diseño, ese elemento ocultará la superposición.

Ordenación #

clerk-omnisearch-sort

Detecta los menús desplegables de ordenación y les añade listeners.

Para obtener un elemento de ordenación en el diseño, agrégalo al elemento seleccionado, por ejemplo un desplegable. Para que funcione, el elemento debe tener el siguiente formato value:[desc|asc], es decir, el valor por el que ordenar, dos puntos, y luego desc o asc. Opcionalmente puedes agregar un atributo data-sort-type si quieres ordenar 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 facetas que no coincidan con la consulta.

La clase, cuando está presente en una página web, busca si existen elementos de búsqueda de facetas. Las búsquedas de facetas permiten a los usuarios buscar dentro de las facetas. Para que funcione, el elemento debe tener un valor de cadena.

Limpieza total #

clerk-omnisearch-full-reset

Al hacer clic, los elementos con esta clase limpian todas las facetas seleccionadas y reinician la búsqueda.

Limpiar facetas #

clerk-omnisearch-facet-full-reset

Al hacer clic, los elementos con esta clase deseleccionan todas las facetas activas. Esto suele encontrarse en un botón de tipo “Limpiar todo” dentro de un grupo de facetas, permitiendo a los usuarios reiniciar todos sus filtros de manera sencilla.

Limpiar grupo #

clerk-omnisearch-facet-group-reset

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

Para ofrecer la función de deseleccionar un grupo entero de facetas, un elemento puede tener esta clase. Al activarse (por ejemplo, hacer clic), todos los elementos de su grupo se deseleccionan. Para que funcione, el elemento debe tener el grupo a limpiar como atributo data-facet-group.

Limpiar faceta #

clerk-omnisearch-facet-reset

Los elementos con esta clase deben deseleccionar un solo elemento según el par de atributos group/value dado.

Esta clase está pensada para escenarios donde sea necesario deseleccionar una sola faceta. Un elemento con esta clase puede asociarse a una faceta concreta en un grupo dándole ambos atributos data-facet-group y data-facet-value. Al activarse, solo deselecciona su faceta asociada y deja las demás sin cambios.

Facet Click #

clerk-facet

Los elementos con esta clase serán tratados como facetas seleccionables.

Todas las facetas deben tener esta clase junto a los atributos data-facet-group y data-facet-value, para saber qué está seleccionando el cliente.