Dokumentace iframe widgetu Transparentní účet KB

1. Úvod

Řešení umožňuje zobrazovat zvolený transparentní účet Komerční banky na vašich stránkách formou iframe widgetu. Widget disponuje výchozím vzhledem, který můžete přenastavit přilinkováním vlastních CSS stylů. Widgetu můžete nastavit v podstatě libovolnou šířku, jeho výška se přizpůsobí automaticky. Tato dokumentace zahrnuje návod, jak iframe vložit do vašich stránek a jak ho customizovat, aby lépe zapadal do vzhledu vašich stránek.

2. Požadavky a kompatibilita

Samotný widget je optimalizovaný pro internetové prohlížeče Internet Explorer 9+ a aktuální verze moderních prohlížečů Google Chrome, Mozilla Firefox, Opera a Safari.

Možnost automatického přizpůsobování výšky iframu jeho obsahu, je založená na metodě HTML5 postMessage a podporují ji všechny výše uvedené prohlížeče.

3. Vložení widgetu do vašich stránek

Na požadované místo v kódu vašich stránek vložte následující definice:

<iframe id="kb-widget-transparent-account" class="kb-widget" width="320" height="430" src="https://www.kb.cz/cs/transparentni-ucty/widget/{id-klienta}/detail-uctu-{cislo-uctu}.shtml" frameborder="0"></iframe>
<script type="text/javascript" src="https://www.kb.cz/js/production/widget-transparent-account-iframe.js"></script>

První řádek kódu vkládá samotný iframe. Šířku iframu, tj. hodnotu atributu width můžete v podstatě libovolně přenastavit. Jako minimum při výchozím vzhledu doporučujeme 280 pixelů, pokud si styly customizujete, je možné použít i menší šířku. Šířku iframu můžete nastavit rovněž v procentech, zadáte-li např. 100%, využije iframe celou šířku nadřazeného prvku, do kterého iframe vkládáte. Pakliže implementujete i druhý řádek kódu (skript widget-transparent-account-iframe.js), má nastavená výška iframu, tj. hodnota atributu height význam pouze při výchozím načtení iframu, bezprostředně po něm je jeho výška automaticky upravena na výšku podle skutečného obsahu iframu. V případě, že možnost automatického přizpůsobení výšky nevyužijete, nastavte dostatečnou výšku, aby byl obsah iframu plně viditelný v závislosti na zvolené šířce widgetu a reálném obsahu widgetu. V atributu src je potřeba nastavit URL k widgetu požadovaného transparentního účtu. URL je v uvedeném formátu, konkrétní hodnotu {id-klienta}{cislo-uctu} je možné odvodit z adresy detailu příslušného transparentního účtu, který je dostupný ze seznamu transparentních účtů https://www.kb.cz/cs/transparentni-ucty/.

Druhý řádek kódu zajišťuje automatické přizpůsobení výšky iframu podle jeho obsahu. Vzhledem k tomu, že výška obsahu iframu se může měnit ať už v závislosti na nastavených uživatelských stylech nebo v závislosti na změnách, které může průběžně provádět Komerční banka ve výchozím vzhledu widgetu, je implementace této možnosti doporučována. V opačném případě není možné ze strany dodavatele widgetu garantovat trvalou plnou viditelnost obsahu widgetu.

Na pořadí řádků v těchto definicích záleží! Definice uvádějte vždy v tomto pořadí.

Ukázka výsledného iframe ve výchozím vzhledu:

Ukázka výsledného iframe ve výchozím vzhledu

4. Customizace vzhledu obsahu iframe widgetu

Ke customizaci vzhledu obsahu iframe widgetu je nutná alespoň základní znalost principů kaskádových stylů a znalost použité HTML struktury widgetu (viz dále). Vzhled widgetu je možné přizpůsobit přilinkováním vlastních CSS definic pomocí parametru css. Jako hodnotu tohoto parametru vložte absolutní cestu (včetně https://) k příslušnému CSS souboru na vašem webu. Definicemi obsaženými v tomto CSS souboru můžete předeklarovat CSS výchozího vzhledu.

4.1. Ukázka přilinkování vlastních stylů v deklaraci iframu

<iframe id="kb-widget-transparent-account" class="kb-widget" width="320" height="430" src="https://www.kb.cz/cs/transparentni-ucty/widget/{id-klienta}/detail-uctu-{cislo-uctu}.shtml?css=https://www.kb.cz/widget/transparentni-ucet/css/custom-example.css" frameborder="0"></iframe>

Jakožto výchozí šablona pro vytvoření vlastních CSS definic vám poslouží soubor https://www.kb.cz/widget/transparentni-ucet/css/custom-template.css. Ten si stáhněte, upravte dle vlastních potřeb, uložte na svůj web pod libovolným názvem a na libovolnou cestu a přilinkujte k iframu tak, jak je popsáno výše. Ze vzorové šablony zároveň vyplývá použitá HTML struktura widgetu, resp. pojmenování jednotlivých tříd.

Definice, které chcete zachovat stejné jako ve výchozím vzhledu, z vašeho customizovaného CSS souboru vymažte, jejich redeklarace stejnými hodnotami by byla zbytečná. Zachovejte pouze ty definice, které nějakým způsobem mění nebo doplňují výchozí nastavení.

4.2. Widget z hlediska HTML struktury

Widget je složen z těchto HTML komponent, v závorce jsou uvedeny přiřazené custom třídy (viz také 4.3.):

  • tělo widgetu - tag <body> (.custom-color, .custom-background, .custom-font, .custom-font-size)
    • obal widgetu - tag <div class="main"> (.custom-widget-border)
      • hlavní nadpis - tag <h1> (.custom-h1-font-size, .custom-highlight-color-set)
      • obal vlastního obsahu widgetu - tag <div class="in"> (.custom-content-border)
        • obal zobrazovaných parametrů k danému účtu - <div class="box"> (.custom-box-border, .custom-border-radius)
          • jednotlivé parametry k danému účtu - tag <p> (.custom-p-font-size, .custom-p-color)
            • popisek názvu parametru - tag <span class="label"> (.custom-label-font-size, .custom-label-color)
            • hodnota parametru - tag <strong class="value"> (.custom-value-font-size, .custom-value-color)
        • údaj o poslední aktualizaci widgetu - tag <p class="note"> (.custom-note-font-size, .custom-note-color)
        • obal tlačítka - tag <p class="btn-container">
          • tlačítko s odkazem do detailu transparentního účtu - tag <a class="btn btn-default"> (.custom-highlight-border, .custom-btn-font-size, .custom-highlight-color-set, .custom-highlight-color-set-hover, .custom-border-radius, .custom-transition)

4.3. Třídy pro rychlou redeklaraci základních vlastností

K dispozici je sada tříd s prefixem custom-, které jsou určené pro rychlou redeklaraci některých společných základních vlastností jako jsou velikosti písma, barvy písma, pozadí a rámečků apod.:

  • .custom-color - třída pro obecnou definici barvy písma, nastavená na těle widgetu
  • .custom-background - třída pro obecnou definici barvy pozadí, nastavená na těle widgetu
  • .custom-font - třída pro obecnou definici vlastnosti font-family, nastavená na těle widgetu
  • .custom-font-size - třída pro definici výchozí velikosti písma, line-height a font-weight, nastavená na těle widgetu
  • .custom-widget-border - třída pro definici rámečku, nastavená na obalu widgetu
  • .custom-content-border - třída pro definici rámečku, nastavená na obalu vlastního obsahu widgetu
  • .custom-box-border - třída pro definici rámečku, nastavená na obalu zobrazovaných parametrů k danému účtu
  • .custom-highlight-border - třída pro definici rámečku, nastavená na tlačítku
  • .custom-h1-font-size - třída pro definici velikosti písma, nastavená na hlavnímu nadpisu
  • .custom-p-font-size - třída pro definici velikosti písma, nastavená na parametrech k danému účtu
  • .custom-note-font-size - třída pro definici velikosti písma, nastavená na údaji o poslední aktualizaci widgetu
  • .custom-label-font-size - třída pro definici velikosti písma, nastavená na popisku názvu parametru
  • .custom-value-font-size - třída pro definici velikosti písma, nastavená na hodnotě parametru
  • .custom-btn-font-size - třída pro definici velikosti písma, nastavená na tlačítku
  • .custom-p-color - třída pro definici barvy písma, nastavená na parametrech k danému účtu
  • .custom-note-color - třída pro definici barvy písma, nastavená na údaji o poslední aktualizaci widgetu
  • .custom-label-color - třída pro definici barvy písma, nastavená na popisku názvu parametru
  • .custom-value-color - třída pro definici barvy písma, nastavená na hodnotě parametru
  • .custom-highlight-color-set - třída pro definici barvy písma a pozadí, nastavená na hlavním nadpisu a tlačítku
  • .custom-highlight-color-set-hover - třída pro definici barvy písma a pozadí ve stavu :hover, nastavená na tlačítku
  • .custom-border-radius - třída pro definici vlastnosti border-radius, nastavená na obalu parametrů k danému účtu a tlačítku
  • .custom-transition - třída pro definici vlastnosti transition, nastavená na tlačítku

Z tohoto popisu je zřejmé, že chcete-li například jednoduše sladit barvu písma a pozadí widgetu s barvami, které používáte na svém webu, předeklarujete třídy .custom-color.custom-background apod.

4.4. Redeklarace jednotlivých komponent

Jednotlivé komponenty (body, div.main, div.in, p, .btn atd.), resp. jejich jednotlivé vlastnosti můžete pochopitelně předeklarovat také samostatně bez použití těchto .custom- tříd. Jakožto vzor použijte šablonu https://www.kb.cz/widget/transparentni-ucet/css/custom-template.css s výchozí definicí všech nastavených vizuálních vlastností. Inspirovat se můžete také v ukázkovém customizačním souboru https://www.kb.cz/widget/transparentni-ucet/css/custom-example.css.

Ukázka výsledného iframe v customizovaném vzhledu:

Ukázka výsledného iframe v customizovaném vzhledu

6. Podpora

V případě problémů s widgetem kontaktujte kb@fg.cz.