Support v pravém dolním rohu

COMEX umí přidat k přihlášené aplikaci plovoucí prvek supportu. V zákaznických aplikacích se může zobrazovat jako chat, ikona nápovědy nebo záchranný kruh — vzhled určuje zvolený soubor ikony. Kliknutím se otevře bublina s obsahem z HTML souboru a podle konfigurace také tlačítkem pro založení požadavku.

Nejde o samostatný control ani o obsah definovaný ve stránce .cxd. Runtime jej po sestavení stránky vloží přímo do document.body jako cxd-support.

Rychlé nastavení

Nastavení patří do zákaznického custom/custom-script.js; výchozí hodnoty a komentovaný vzor jsou v COMEX public/custom/default/custom-script.js.

$custom.Support.enabled = true;
$custom.Support.icon = "/unk/comex/images/help.svg";
$custom.Support.contentPage = "/unk/comex/custom/support.html";

// Zvolte nejvýše jeden způsob odeslání požadavku.
$custom.Support.requestAction = "admin_nacist_ticket_7560";
$custom.Support.requestPage = "";

Nastavení	Výchozí hodnota	Význam v runtime
`$custom.Support.enabled`	`false`	Musí být přesně boolean `true`; jiná pravdivá hodnota, například řetězec `"true"` nebo `"y"`, support nezapne.
`$custom.Support.icon`	`"/unk/comex/images/support.svg"`	URL ikony hlavního tlačítka. Runtime ji vytvoří přes `COMEX.Page.createIcon()`. Ikonu pro zavření nelze tímto nastavením změnit: je vždy `/unk/comex/images/close.svg`.
`$custom.Support.contentPage`	`"/unk/comex/custom/support.htm"`	URL HTML dokumentu načítaného do bubliny metodou `GET`. Prázdná hodnota je povolená, pokud je nastaveno alespoň jedno z nastavení odeslání.
`$custom.Support.requestAction`	`""`	Název COMEX akce, kterou má tlačítko požadavku spustit. Akce se připraví už při otevření bubliny; po stisku tlačítka běží běžným mechanismem `action/run`.
`$custom.Support.requestPage`	`""`	URL otevřená po stisku tlačítka požadavku v novém okně/záložce (`window.open(url, "_blank")`). Použije se jen tehdy, když `requestAction` není vyplněno.

Název hlavního tlačítka i automaticky vloženého tlačítka nejsou součástí těchto nastavení. Berou se z jazykových klíčů needSupport a supportRequest v public/labels/comex-page.lng; v češtině jsou to „Potřebuji poradit“ a „Zadat požadavek“.

Kdy se support vytvoří

COMEX.Page.Support.init() se volá po sestavení rámců stránky, po události load těla stránky a po COMEX.Controls.find(). Runtime support vůbec nevytvoří, jestliže platí alespoň jedna z následujících podmínek:

uživatel není známý (COMEX.User.known === false),
enabled !== true,
současně jsou prázdné contentPage, requestAction i requestPage.

Z toho plyne, že ikona není anonymní kontaktní widget. Je určena pro přihlášeného uživatele COMEXu a pro konfiguraci s alespoň jedním zdrojem obsahu nebo způsobem předání požadavku.

Komponenta se v rámci načtené stránky vytvoří pouze jednou. Při dalším otevření se ale obsah bubliny znovu vyprázdní, zobrazí se loader a contentPage se znovu načte. Pro požadovanou akci se již existující komponenta akce znovu nevytváří.

Chování a výsledný DOM

Po inicializaci má prvek zjednodušeně tuto podobu:

<cxd-support class="button">
  <svg><!-- $custom.Support.icon --></svg>
  <svg><!-- /unk/comex/images/close.svg --></svg>
  <span>Potřebuji poradit</span>
  <cxd-supp-win>
    <cxd-content><!-- načtené HTML a případně tlačítko --></cxd-content>
  </cxd-supp-win>
</cxd-support>

Kliknutí na tlačítko přepíná atribut showed="y". Kliknutí do cxd-content se nezavírá; kliknutí kamkoli jinam v dokumentu bublinu zavře. Implementace supportu výslovně neobsluhuje klávesu Escape ani správu fokusu.

Styl v public/styles/comex-page.css dává prvku tyto pevné vlastnosti:

je fixovaný 10px od pravého i spodního okraje, standardně má kruhový rozměr 46 × 46px;
při hoveru i při showed="y" se rozšíří na 200px; při otevření je pozadí červené #c00 a místo zákaznické ikony se zobrazí křížek;
okno je absolutně umístěno 56px nad tlačítkem, má šířku 352px, nejvýše calc(100vw - 20px), bílé pozadí, stín a malou šipku k tlačítku;
výška okna se po dokončení načtení nastaví na skutečnou výšku obsahu se zpožděním 100 ms; obsah má overflow: hidden, proto dlouhý text nepočítá s vlastním scrollbarem.

Obsahová stránka `support.html`

contentPage je obyčejný HTML dokument uložený typicky v web/comex/custom/support.html a publikovaný například jako /unk/comex/custom/support.html.

Při každém otevření runtime:

vloží do bubliny loader /unk/comex/images/loader.svg,
odešle asynchronní GET na contentPage,
je-li URL obsahuje /comex, přidá parametr rts s aktuální hodnotou COMEX.getRTS() — platí to i pro URL, kde je /comex jen částí cesty,
z odpovědi odstraní vše před otevíracím <body> a po uzavíracím </body>, včetně konců řádků,
zbývající obsah vloží do cxd-content jako neescapované HTML,
ke každému a[target="_blank"] doplní inline SVG ikonu otevření v nové záložce.

Pokud odpověď tag <body> neobsahuje, regulární výraz nic neodstraní a vloží se celá odpověď. Support neprovádí vlastní sanitizaci HTML. support.html proto musí být důvěryhodný, spravovaný soubor; do něj nevkládejte uživatelský ani jiný neověřený HTML obsah.

HTML, nikoli Markdown

Bublina nepřevádí Markdown na HTML. Soubor musí obsahovat HTML uvnitř body; Markdownové konstrukce jako ## Nadpis nebo **tučně** by se zobrazily jako běžný text. Markdown se používá jen pro tuto produktovou dokumentaci.

Výchozí šablona public/custom/default/support.htm doporučuje následující omezenou sadu prvků, pro něž již existují cílené CSS styly:

Potřeba	Použijte	Runtime styl
Nadpis	`h1`, `h2`, `h3`	Tučné nadpisy o velikosti 17, 15 a 13 px.
Oddělený textový blok	`div`	Blok s horním okrajem 6 px; po nadpisu 18 px.
Dělící čára	`hr`	Čára `#ccc` s vertikálním odsazením 18 px.
Zvýraznění	`strong` nebo `b`	Tučné písmo.
Kurzíva	`em` nebo `i`	Kurzívní písmo.
Nový řádek	`br`	Řádkování pro text v bublině.
Odkaz	`a`	Barva `--button-background`, podtržení při hoveru; `target="_blank"` získá ikonu nové záložky.

Obecný text bubliny má velikost 11 px a řádkování 15 px. Vzhledem k pevné šířce bubliny je vhodné držet text i počet bloků krátký.

Následující šablona je plnohodnotný výchozí soubor. Tlačítko „Zadat požadavek“ do ní nepřidávejte: runtime je připojí automaticky, jen pokud je vyplněno requestAction nebo requestPage.

<!doctype html>
<html lang="cs">
  <head>
    <meta charset="utf-8">
    <title>Podpora</title>
  </head>
  <body>
    <h2>Potřebujete poradit?</h2>

    <div><strong>Než zadáte požadavek, zkuste…</strong></div>
    <div>
      <strong>
        <a href="https://example.invalid/faq" target="_blank">Časté dotazy</a>
      </strong>
    </div>

    <hr>

    <div><strong>Aplikační podpora</strong><br></div>
    <div>Po–Pá | 9:00–16:00</div>
  </body>
</html>

head, title a vnější html slouží souboru samotnému; bublina zpracuje pouze obsah body.

Odeslání požadavku

Pokud není vyplněn ani requestAction, ani requestPage, žádné tlačítko pro založení požadavku nevznikne. Je-li vyplněno alespoň jedno z nich, runtime po obsahu HTML vloží tlačítko s ikonou /unk/comex/images/help.svg.

Varianta s `requestPage`

Je-li nastaveno pouze requestPage, kliknutí otevře danou URL v nové záložce. COMEX k URL nepřidává žádné parametry ani trace soubor.

Varianta s `requestAction`

Je-li vyplněno requestAction, má přednost před requestPage při stisku tlačítka. requestPage se v takovém případě nepoužije. contentPage se však stále normálně načítá; nastavení akce obsahovou stránku nevypíná.

Při otevření bubliny runtime pro akci dynamicky vloží komponentu se zdrojem:

comex.action.run:<název-akce>.pointer[common-support]

Tato instance je poté při odeslání spuštěna voláním:

actionModifier.execute(null, passedParams)

Zadání požadavku se proto řídí vstupními možnostmi definované akce úplně stejně jako u kterékoliv jiné COMEX akce. Akce si zachovává svůj seznam parametrů, výchozí a uložené hodnoty, appear-if, povinnost parametrů, volby, dialogy potvrzení i vlastní následné zpracování. Support do ní pouze přidává předané hodnoty.

action/run nejprve připraví všechny parametry z definice akce a až pak hodnotami passedParams přepíše pouze parametry se stejným názvem. Hodnota pro parametr, který v definici akce neexistuje, se zahodí. Parametry s viditelností či povinností vyžadující vstup uživatele se proto nadále chovají standardně.

Předané klíče mají tento význam:

Název parametru v akci	Předaná hodnota
`userId`	`COMEX.User.ID` — ID právě přihlášeného uživatele.
`pageUrl`	`window.appTop.location.href` — URL hlavního aplikačního okna.
`formUrl`	`window.location.href`, ale jen je-li aktuální stránka cover frame; jinak prázdný řetězec.
`trace`	Jméno vytvořeného trace souboru, například `<časová-značka>.xml`; při neúspěšném uložení `err.xml`.

Chce-li akce některou hodnotu použít, musí mít parametr se stejným technickým názvem. V běžném zápisu se o vstupním parametru trace mluví jako o $trace, ale jeho název v definici akce je trace.

Trace soubor předaný akci

Trace se ukládá vždy při odeslání přes requestAction, i kdyby akce parametr trace vůbec nedefinovala. Samotný upload je synchronní a proběhne ještě před voláním akce:

vytvoří se COMEX.Trace.toXML() a XML deklarace <?xml version="1.0" encoding="utf-8"?>,
klient připraví požadavek save-file s path="user-saves/trace", jménem <časová-značka>.xml, kódováním UTF-8 a typem souboru XML,
XML trace se vloží do požadavku a odešle přes COMEX.User.solve(),
pouze odpověď obsahující /response/save-file s atributem type="ok" potvrzuje, že soubor byl uložen,
akce se spustí i při chybě ukládání; místo vytvořeného jména dostane trace = "err.xml".

COMEX předává do parametru trace jen jméno souboru, nikoli hotový odkaz. Má-li akce vstup trace, sestaví její implementace odkaz na soubor v uživatelském úložišti jako:

user-saves/trace/<hodnota-parametru-trace>

Například pro trace = "2026-10-01-123456.xml" odpovídá cesta user-saves/trace/2026-10-01-123456.xml. Akce musí zvlášť ošetřit hodnotu err.xml: je to signál selhaného uploadu, ne potvrzení, že takový trace soubor existuje.

Vazba trace souboru na uživatelské úložiště je důležitá i pro oprávnění. Akce by neměla z parametru nekontrolovaně sestavovat veřejný odkaz ani jej sdílet mimo očekávaný proces podpory.

Co obsahuje trace XML

COMEX.Trace udržuje diagnostickou informaci v sessionStorage pod klíčem __trc__nfo a při serializaci ji doplní aktuálním snapshotem LSV. Trace je verze 2 a jeho přesná množina položek závisí na tom, co uživatel v dané session provedl.

Zjednodušená struktura vypadá takto:

<trace ver="2" uid="…" user="…" imper="…" lang="…">
  <page url="…" title="…" win="window|frame" comex="…" app="…">
    <event dtime="YYYY-MM-DD hh:mm:ss" source="…" type="…" extra="…" />
    <solve dtime="…" duration-ms="…" status="ok|error" origin="…">
      <action call-type="…" name="…">
        <param name="…" value="…" />
        <pdk-list-item pdk="…" type="…" vtype="…" />
      </action>
      <error detail="…" number="…" severity="…" />
    </solve>
  </page>
  <lsv name="…" value="…" />
</trace>

Část	Zdroj a obsah
Atributy `trace`	Verze trace, ID a jméno uživatele, případně jméno impersonovaného uživatele, a jazyk.
`page`	Navštívená URL, titulek dokumentu, zda šlo o hlavní okno nebo frame, a verze/release COMEXu a aplikace. Stejná URL sdružuje více položek do jedné stránky trace.
`event`	Čas, zdroj, typ a volitelný doplněk události. Při připravené stránce COMEX například zapisuje událost `page/ready`.
`solve`	Normalizovaný záznam podporovaných serverových požadavků: čas, původ, trvání, stav a vybrané údaje požadavku/odpovědi. Sledují se akce, `get-draft`, `save-draft`, načtení dokumentu a uložení dokumentu, včetně jejich transformovaných variant.
`action` v `solve`	U akce typ volání a jméno, dále hodnoty parametrů a položky PDK listu.
`error`	Při odpovědi se stavem `error` detail, číslo a závažnost dostupné z odpovědi.
`lsv`	Aktuální úplný seznam Local Stored Values v okamžiku serializace.

Požadavek save-file, kterým se právě ukládá trace, není jedním ze sledovaných typů COMEX.Trace.addSolve(). Nový trace proto obsahuje dosavadní diagnostiku session, ne záznam svého vlastního uploadu.

Trace může obsahovat údaje o uživateli, URL, jména a hodnoty parametrů akcí, PDK položky i LSV. Před zapojením supportu ověřte, zda je takový rozsah dat přiměřený pravidlům projektu, kdo má přístup do user-saves/trace a jak dlouho budou soubory uchovány.

Ověřovací scénář nasazení

Přihlaste se jako běžný uživatel a nastavte enabled = true; ověřte vznik ikony v pravém dolním rohu. Pro anonymního uživatele se ikona objevit nesmí.
Otevřete a zavřete bublinu tlačítkem i kliknutím mimo ni. Ověřte načtení contentPage, správnou výšku a ikonu u každého odkazu s target="_blank".
Ověřte, že HTML šablona obsahuje body; zkontrolujte nadpisy, bloky, hr, tučný text a externí odkaz. Markdown do souboru nevkládejte.
Pro konfiguraci pouze s requestPage ověřte otevření URL v nové záložce.
Pro konfiguraci s requestAction ověřte standardní dialog/vstupy akce. Definujte jí parametr trace, po odeslání najděte odpovídající XML v user-saves/trace/ a ověřte, že akce skládá cestu z této složky a předaného názvu souboru.
Ověřte také chybovou větev ukládání podle provozních možností: akce musí bezpečně zvládnout trace = "err.xml".

Související zdroje

Custom nastavení aplikace — historický přehled častých nastavení custom-script.
COMEX.Action.Run.Modifier.execute — generované API volané supportem při requestAction.
public/scripts/comex-page.js — COMEX.Page.Support, COMEX.Trace a COMEX.Page.__loadAction.
public/modifiers/action/run/action-run.js — příprava, přepis a zobrazení parametrů standardní akce.
public/styles/comex-page.css — vzhled cxd-support a cxd-supp-win.
public/custom/default/support.htm — výchozí HTML šablona.

Rychlé nastavení​

Kdy se support vytvoří​

Chování a výsledný DOM​

Obsahová stránka support.html​

HTML, nikoli Markdown​

Odeslání požadavku​

Varianta s requestPage​

Varianta s requestAction​

Trace soubor předaný akci​

Co obsahuje trace XML​

Ověřovací scénář nasazení​

Související zdroje​