Instalace UpSearch Plugin

Tato příručka vás provede instalací a konfigurací UpSearch Plugin na vašem webu.

Požadavky

Přístupový token k projektu v API UpSearch (apiToken)
Stránka pro zobrazení výsledků vyhledávání

Vložení našeptávače

Našeptávač se do stránky vkládá následujícím snippetem:

<!DOCTYPE html>
<html lang="cs">
<head>
    <!-- ... -->
    <link href="https://cdn.upsearch.cz/projects/PROJEKT/upsearch.css" rel="stylesheet" />
</head>
<body>
    <!-- ... -->
    <div id="suggestElement"></div>

    <script defer src="https://cdn.upsearch.cz/projects/PROJEKT/upSearchSuggest.js"></script>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            window.upSearchSuggest('#suggestElement', {
                resultsPageUrlPath: '/vysledky-vyhledavani',
                apiToken: 'VAS_API_TOKEN',
            });
        });
    </script>
</body>
</html>

Důležité

HTML element pro vložení našeptávače musí existovat v čase spuštění scriptu. Optimální umístění scriptu je těsně před uzavírací značku </body>.

Asynchronní inicializace

Pokud potřebujete script spustit asynchronně:

<script>
    document.addEventListener('DOMContentLoaded', function() {
        window.upSearchSuggest('#suggestElement', {
            resultsPageUrlPath: '/vysledky-vyhledavani',
            apiToken: 'VAS_API_TOKEN',
        });
    });
</script>

Vložení stránky s výsledky

Na stránku s výsledky vložte komponentu upSearchResults:

<!DOCTYPE html>
<html lang="cs">
<head>
    <!-- ... -->
    <link href="https://cdn.upsearch.cz/projects/PROJEKT/upsearch.css" rel="stylesheet" />
</head>
<body>
    <div id="resultsElement"></div>

    <script defer src="https://cdn.upsearch.cz/projects/PROJEKT/upSearchResults.js"></script>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            window.upSearchResults('#resultsElement', {
                apiToken: 'VAS_API_TOKEN',
            });
        });
    </script>
</body>
</html>

Konfigurace

Základní parametry

Parametr	Typ	Povinný	Popis
`apiToken`	string	✅	Přístupový token k projektu v API UpSearch
`resultsPageUrlPath`	string	✅*	URL cesta ke stránce s výsledky (* povinné pro suggest)
`env`	`'production'` \| `'test'`	❌	Prostředí API (výchozí: `'production'`)
`status`	`'published'` \| `'draft'`	❌	Načíst publikovanou nebo draft konfiguraci z Designeru
`cssUrl`	string	❌	URL vlastního CSS souboru

Ceníky a měna

Parametr	Typ	Výchozí	Popis
`currencyCode`	string	`''`	ISO kód měny (např. `'CZK'`, `'EUR'`)
`priceLists`	string	`''`	Kódy ceníků oddělené čárkou
`whiteListGroup`	string	`''`	Kód skupiny pro whitelist

Zobrazení produktů

Parametr	Typ	Výchozí	Popis
`showBadges`	boolean	`true`	Zobrazit štítky produktů
`showOldPrice`	boolean	`true`	Zobrazit původní cenu
`showDiscountInPercent`	boolean	`true`	Zobrazit slevu v procentech
`showStockInfo`	boolean	`true`	Zobrazit informaci o dostupnosti
`showBranchStockInfo`	boolean	`true`	Zobrazit dostupnost na pobočkách
`showBrandName`	boolean	`false`	Zobrazit název značky
`showInlineFeatures`	boolean	`false`	Zobrazit vlastnosti produktu inline
`showCustomProperty1`	boolean	`false`	Zobrazit custom_property_1
`showCustomProperty2`	boolean	`false`	Zobrazit custom_property_2
`highlightSearchPhrase`	boolean	`true`	Zvýraznit hledanou frázi ve výsledcích

Košík a wishlist

Parametr	Typ	Výchozí	Popis
`showAddToCart`	boolean	`false`	Zobrazit tlačítko "Přidat do košíku"
`addToCart`	string	-	Název globální funkce pro přidání do košíku
`showWishListButton`	boolean	`false`	Zobrazit tlačítko wishlistu
`wishLists`	string	`''`	ID produktů ve wishlistu (oddělené čárkou)
`handleWishList`	string	-	Název globální funkce pro wishlist

Příklad integrace košíku

// Definujte globální funkci pro přidání do košíku
window.addProductToCart = function(productCode) {
    // Vaše logika pro přidání do košíku
    console.log('Přidávám produkt:', productCode);
};

window.upSearchSuggest('#suggestElement', {
    apiToken: 'VAS_API_TOKEN',
    resultsPageUrlPath: '/vysledky',
    showAddToCart: true,
    addToCart: 'addProductToCart', // název funkce
});

Konfigurace našeptávače (Suggest)

Parametr	Typ	Výchozí	Popis
`injectAs`	`'input'` \| `'button'`	`'input'`	Vložit jako input nebo button
`layout`	`'row'` \| `'grid'`	`'row'`	Layout výsledků
`productBoxLayout`	`'inline'` \| `'card'`	`'inline'`	Layout produktových karet
`phraseBoxLayout`	`'inline'` \| `'block'`	`'inline'`	Layout frází
`showTopProduct`	boolean	`false`	Zobrazit první produkt jako "top"
`showTotalCount`	boolean	`false`	Zobrazit celkový počet výsledků
`showSimpleBlockIcon`	boolean	`true`	Zobrazit ikony u kategorií/značek
`showSimpleBlockCount`	boolean	`true`	Zobrazit počet u kategorií/značek
`showInputPlaceholder`	boolean	`true`	Zobrazit placeholder v inputu
`showPoweredByInSidebar`	boolean	`true`	Zobrazit "Powered by UpSearch"
`useSuggestMobileFullscreenLayout`	boolean	`false`	Fullscreen layout na mobilu
`suggestAbsolutePosition`	boolean	`false`	Absolutní pozicování suggestu
`useCollectionsTabs`	boolean	`false`	Použít záložky pro kolekce

Konfigurace výsledků (Results)

Parametr	Typ	Výchozí	Popis
`showSearchInput`	boolean	`true`	Zobrazit vyhledávací input
`showPaging`	boolean	`true`	Zobrazit stránkování
`showLoadMore`	boolean	`true`	Zobrazit tlačítko "Načíst další"
`infiniteScrolling`	boolean	`false`	Automatické načítání při scrollu
`showSorting`	boolean	`false`	Zobrazit řazení
`showTextSearchInFilters`	boolean	`true`	Vyhledávání v hodnotách filtrů
`showItemsCountInTabs`	boolean	`true`	Počet položek v záložkách
`collapsibleFilters`	boolean	`false`	Sbalitelné filtry
`showArticleImage`	boolean	`true`	Obrázky u článků
`minFilterItemsToSearch`	number	`6`	Min. položek pro zobrazení vyhledávání ve filtru

Dynamický obsah stránky

Parametr	Typ	Výchozí	Popis
`dynamicH1`	boolean	`false`	Dynamicky měnit H1 nadpis
`dynamicH1PhraseIsSearch`	boolean	`true`	Použít "Vyhledávání" místo "Výsledky"
`dynamicTitle`	boolean	`false`	Dynamicky měnit title stránky
`dynamicTitleStaticPart`	string	-	Statická část přidaná k title

Tlačítka a ikony

Parametr	Typ	Výchozí	Popis
`searchButtonVariant`	`'primary'` \| `'secondary'` \| `'blank'`	`'primary'`	Varianta tlačítka hledání
`searchButtonSize`	`'sm'` \| `'md'`	`'sm'`	Velikost tlačítka
`searchButtonInsideInput`	boolean	`false`	Tlačítko uvnitř inputu
`showSearchButtonText`	boolean	`true`	Text na tlačítku hledání
`searchButtonIcon`	string	-	Vlastní ikona (SVG string)
`icons`	object	-	Objekt s vlastními ikonami `{ iconName: '<svg>...</svg>' }`

Vlastní překlady

window.upSearchSuggest('#suggestElement', {
    apiToken: 'VAS_API_TOKEN',
    resultsPageUrlPath: '/vysledky',
    translations: {
        cs: {
            'suggest.placeholder': 'Hledejte produkty...',
            'suggest.showAll': 'Zobrazit všechny výsledky',
        }
    }
});

Odstranění komponenty

V případě potřeby můžete komponentu odstranit pomocí destruktoru:

const destructSuggest = window.upSearchSuggest('#suggestElement', {
    resultsPageUrlPath: '/vysledky-vyhledavani',
    apiToken: 'VAS_API_TOKEN',
});

// Později pro odstranění:
destructSuggest();

Stylování

Struktura CSS

Všechny CSS třídy jsou prefixovány .up-* pro zamezení kolizí se styly vašeho webu.

styles/
├── base/        # Proměnné, mixiny, typografie
├── components/  # Styly jednotlivých komponent
├── core/        # Základní prvky (input, button, price)
└── layout/      # Layout wrappery

CSS Wrappery

Plugin používá následující ID wrappery:

#upsearch - Hlavní wrap pro input a našeptávač
#upsearch-button - Wrap pro samostatný button
#upsearch-results - Wrap pro stránku s výsledky

Specificita

Pro přepsání stylů použijte ID selektor:

#upsearch .up-price {
    font-weight: bold;
}

Reset CSS

Plugin používá CSS reset pro izolaci od stylů webu:

#upsearch {
    all: revert;
}
#upsearch * {
    all: revert;
}

Řešení problémů

Styly se nepřepisují

Pro weby s vysokou specificitou selektorů může být potřeba:

Použít inline styly
Přidat !important do vlastních stylů
Zvýšit specificitu selektorů

Komponenta se nezobrazuje

Zkontrolujte, že element s daným selektorem existuje v DOM
Ověřte, že script je načtený po elementu
Zkontrolujte konzoli prohlížeče pro chyby
Ověřte platnost apiToken

Testovací prostředí

Pro testování použijte parametr env:

window.upSearchSuggest('#suggestElement', {
    apiToken: 'VAS_API_TOKEN',
    resultsPageUrlPath: '/vysledky',
    env: 'test', // použije api.upsearch.praguebest.cz
});

Požadavky​

Vložení našeptávače​

Asynchronní inicializace​

Vložení stránky s výsledky​

Konfigurace​

Základní parametry​

Ceníky a měna​

Zobrazení produktů​

Košík a wishlist​

Příklad integrace košíku​

Konfigurace našeptávače (Suggest)​

Konfigurace výsledků (Results)​

Dynamický obsah stránky​

Tlačítka a ikony​

Vlastní překlady​

Odstranění komponenty​

Stylování​

Struktura CSS​

CSS Wrappery​

Reset CSS​

Řešení problémů​

Styly se nepřepisují​

Komponenta se nezobrazuje​

Testovací prostředí​