Přehled

Systém úprav umožňuje rozšířit uživatelské rozhraní přidáním vlastních tlačítek, panelů, odkazů na pole a vizuálního stylu do různých částí aplikace. Tyto úpravy jsou specifické pro entitu a lze je nakonfigurovat tak, aby se zobrazovaly v různých kontextech na základě uživatelských oprávnění, stavu systému a vlastních podmínek.

Čtyři typy úprav

• Vlastní tlačítka — Interaktivní akce v datových mřížkách a detailech
• Vlastní panely — Panely s doplňujícími informacemi v rozhraní editoru
• Vlastní odkazy — Odkazy na úrovni polí do externích systémů na základě dat záznamu
• Barvy sloupců — Podmíněné barvy pozadí buněk v datových mřížkách

card: Custom Buttons
Interaktivní tlačítka, která se zobrazují v datových mřížkách nebo detailech dat a mohou provádět vlastní akce na vybraných záznamech. Podporují otevírání URL s kontextovými proměnnými nebo spouštění automatizovaných pracovních postupů.
card: Custom Panels
Sbalitelné panely, které se zobrazují v rozhraní editoru a zobrazují doplňující informace, vkládají externí obsah nebo poskytují vlastní ovládací prvky pro vylepšené pracovní postupy.
card: Custom Links
Odkazy na úrovni polí, které se zobrazují v polích editoru a otevírají externí aplikace s kontextovými daty. Viditelné pouze v případě, že pole má hodnotu a jsou splněny volitelné podmínky.
card: Column Colours
Podmíněné barvy pozadí pro buňky datové mřížky na základě výrazů filtru. Aplikujte na všechny sloupce nebo konkrétní sloupce pro vizuální zvýraznění dat.

Klíčové schopnosti
- Specifické pro entitu — Připojte úpravy k jakékoli datové entitě
- Kontextově závislé — Získejte přístup k informacím o uživateli, vybraným záznamům a stavu systému
- Podmíněná viditelnost — Zobrazit/skrýt na základě vlastních výrazů filtru
- Vědomé o sadě změn a režimu jen pro čtení — Respektujte systémové režimy a oprávnění

Vlastní tlačítka [badge:Buttons|warning]

Interaktivní tlačítka, která vylepšují funkčnost seznamu dat nebo detailu dat

[try:/customButtons|Spravovat vlastní tlačítka →|right]

Klíčové vlastnosti

• Zobrazují se v datových mřížkách vedle standardních akčních tlačítek
• Provádějí vlastní akce na vybraných záznamech
• Podporují výběr jednoho i více záznamů
• Mohou být podmíněně zobrazeny na základě stavu záznamu
• Respektují omezení sady změn a režimu jen pro čtení

Konfigurační pole

Základní vlastnosti

• name — Popisek tlačítka zobrazený uživatelům
• entityId — Cílová entita pro tlačítko
• icon — Ikona zobrazená na tlačítku
• color — Barevný motiv tlačítka

Chování

• allowMultiple — Zda tlačítko funguje s více vybranými záznamy
• condition — Volitelný výraz filtru pro povolení/zakázání tlačítka
• action — Typ akce: “openUrl” nebo “runAutomation”
• url — Cílová URL (pro akci openUrl)
• automation_id — Cílová automatizace (pro akci runAutomation)

Řízení viditelnosti

• allowInChangeSet — Zobrazit tlačítko, když je aktivní sada změn
• allowInReadOnly — Zobrazit tlačítko v režimu jen pro čtení

Typy akcí

openUrl — Akce Otevřít URL

Otevře URL v prohlížeči s kontextovými informacemi z uživatelského rozhraní. To umožňuje výkonné vlastní integrace a připojení k externím systémům.

Dostupné kontextové proměnné:

• {user.id} — ID aktuálního uživatele
• {user.email} — E-mail aktuálního uživatele
• {selectedIds} — Seznam ID vybraných záznamů oddělený čárkami
• {entityId} — Identifikátor cílové entity
• {orgId} — ID aktuální organizace

Příklad URL:

https://external-system.com/api/export?records={selectedIds}&user={user.id}&org={orgId}

runAutomation — Akce Spustit automatizaci

Spustí předdefinovaný automatizační pracovní postup na vybraných záznamech. To umožňuje komplexní zpracování dat, transformace a provádění obchodní logiky.

Možnosti automatizace:

• Úprava a aktualizace dat
• Výpočty a transformace polí
• Integrace s externími systémy
• Operace dávkového zpracování
• Spouštění pracovních postupů

Příklady použití:

• Hromadné aktualizace cen na základě výpočtů nákladů
• Automatizovaná synchronizace inventáře
• Pracovní postupy obohacování zákaznických dat
• Generování a distribuce sestav

Příklady konfigurací

Příklad akce OpenUrl:

{
  "name": "Export do PDF",
  "entityId": "products",
  "icon": "FileText",
  "color": "blue",
  "allowMultiple": true,
  "allowInChangeSet": false,
  "allowInReadOnly": true,
  "condition": "status = 'active'",
  "action": "openUrl",
  "url": "https://export.company.com/pdf?ids={selectedIds}&user={user.id}"
}

Příklad akce RunAutomation:

{
  "name": "Update Prices",
  "entityId": "products",
  "icon": "euro",
  "color": "green",
  "allowMultiple": true,
  "allowInChangeSet": true,
  "allowInReadOnly": false,
  "condition": "category.code = 'ELEC'",
  "action": "runAutomation",
  "automation_id": "code:bulk-price-update-automation"
}

Vlastní panely [badge:Panels|info]

Sbalitelné panely, které rozšiřují rozhraní editoru

[try:/customPanels|Spravovat vlastní panely→|right]

Klíčové vlastnosti

• Zobrazují se v postranním panelu editoru vedle standardních panelů
• Sbalitelné s koordinovaným chováním rozbalení/sbalení
• Mohou zobrazovat vlastní obsah, data nebo ovládací prvky
• Podporují různé polohy (vlevo, vpravo, nahoře, dole)
• Mohou se zobrazovat v zobrazení seznamu, zobrazení detailu nebo v obou
• Podpora panelů nezávislých na datech s možností requiresData
• Respektují omezení sady změn a režimu jen pro čtení

Konfigurační pole

Základní vlastnosti

• name — Název panelu zobrazený uživatelům
• entityId — Cílová entita pro panel
• icon — Ikona zobrazená v záhlaví panelu
• position — Umístění panelu (vlevo, vpravo, nahoře, dole)
• location — Kde zobrazit panel (seznam, detail, obojí)
• size — Velikost panelu (tiny, small, medium, large)

Obsah a chování

• action — Typ akce: “openUrl” nebo “showHtml”
• body — Obsah HTML k zobrazení (pro akci showHtml)
• url — Cílová URL (pro akci openUrl)
• requiresData — Zda panel závisí na vybraných datech
• condition — Volitelný výraz filtru pro zobrazení/skrytí panelu

Řízení viditelnosti

• allowInChangeSet — Zobrazit panel, když je aktivní sada změn
• allowInReadOnly — Zobrazit panel v režimu jen pro čtení

Typy akcí

openUrl — Akce Otevřít URL

Otevře URL v prohlížeči s kontextovými informacemi z uživatelského rozhraní, stejně jako CustomButtons. To umožňuje externí integrace a dynamický obsah na základě aktuálního kontextu.

Podporuje stejné kontextové proměnné jako CustomButtons:

• {user.id}, {user.email} — Informace o aktuálním uživateli
• {selectedIds} — ID vybraných záznamů
• {entityId}, {orgId} — Kontextové identifikátory

⚠️ Důležité: Požadavky na vkládání Iframe

Když je URL načtena v iframe v rámci aplikace, cílový server musí být správně nakonfigurován:
- `X-Frame-Options: ALLOW-FROM {HOSTNAME}` — Povolit vkládání z vašeho serveru
- `Content-Security-Policy: frame-ancestors 'self' {HOSTNAME}` — Moderní alternativa CSP
- HTTPS je vyžadováno, pokud nadřazená aplikace používá HTTPS (zásady smíšeného obsahu)
- Soubory cookie nemusí fungovat správně kvůli omezením SameSite v iframech mezi zdroji

showHtml — Akce Zobrazit HTML

Zobrazí obsah z pole body jako HTML v panelu. To umožňuje bohatý formátovaný obsah přímo v rozhraní.

Omezení HTML:

• Pro zabezpečení je podporována omezená podmnožina HTML
• JavaScript není povolen
• Externí značky skriptů a obslužné rutiny událostí jsou odfiltrovány
• Jsou podporovány bezpečné značky, jako jsou nadpisy, odstavce, seznamy a základní formátování

Příklad těla HTML:

<h3>Informace o produktu</h3><p>Další podrobnosti o tomto produktu...</p><ul><li>Funkce 1</li><li>Funkce 2</li></ul>

Závislosti dat

Vlastnost requiresData

Řídí, zda panel závisí na aktuálně vybraných datech. Pokud je nastaveno na false, panel lze zobrazit, i když nejsou vybrána žádná data, takže je nezávislý na aktuálním stavu výběru.

• requiresData: true — Panel se zobrazí pouze v případě, že jsou vybrána data. Kontextové proměnné jako selectedIds budou k dispozici.
• requiresData: false — Panel se může zobrazit nezávisle. Užitečné pro text nápovědy, statické informace nebo globální akce.

Příklady konfigurací

Příklad akce ShowHtml:

{
  "name": "Product Help",
  "entityId": "products",
  "icon": "HelpCircle",
  "position": "right",
  "location": "detail",
  "size": "small",
  "requiresData": false,
  "allowInChangeSet": true,
  "allowInReadOnly": true,
  "action": "showHtml",
  "body": "<h3>Product Guidelines</h3><p>Follow these steps when editing products...</p>"
}

Příklad akce OpenUrl:

{
  "name": "Product Analytics",
  "entityId": "products",
  "icon": "BarChart",
  "position": "right",
  "location": "detail",
  "size": "medium",
  "requiresData": true,
  "allowInChangeSet": true,
  "allowInReadOnly": true,
  "action": "openUrl",
  "url": "https://analytics.company.com/product?id={selectedIds}&user={user.id}"
}

Řízení viditelnosti

Pochopení, kdy jsou úpravy zobrazeny nebo skryty

Stavy systému

Režim sady změn

Když je aktivní sada změn, jsou viditelné pouze úpravy s allowInChangeSet: true.

Režim jen pro čtení

Když je v režimu jen pro čtení, jsou viditelné pouze úpravy s allowInReadOnly: true.

Matice viditelnosti

Aspekty vkládání Iframe

Důležité technické požadavky a omezení při vkládání externího obsahu

⚠️ Kritické požadavky na konfiguraci serveru

Externí adresy URL načtené ve vlastních panelech musí být speciálně navrženy pro vkládání iframe. Cílový server MUSÍ poskytovat správné hlavičky zabezpečení HTTP, aby bylo možné vkládání.

Požadované hlavičky HTTP

Kritické — Hlavička X-Frame-Options:

X-Frame-Options: ALLOW-FROM {HOSTNAME}

Použijte skutečnou doménu aplikace. Tato hlavička umožňuje vaší aplikaci vložit externí obsah do iframe.

Moderní alternativa — Zásady zabezpečení obsahu (CSP):

Content-Security-Policy: frame-ancestors 'self' {HOSTNAME}

Moderní prohlížeče preferují CSP před X-Frame-Options. Tato direktiva řídí, které domény mohou vkládat stránku do rámců. Nahraďte skutečnou doménou aplikace.

Doporučeno — Další hlavičky zabezpečení:

X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

Další hlavičky zabezpečení, které zlepšují zabezpečení vloženého obsahu.

Běžné problémy a řešení s iframe

Smíšený obsah HTTPS

Problém: Prohlížeč blokuje obsah HTTP, když nadřazená stránka používá HTTPS

Řešení: Zajistěte, aby všechny externí adresy URL používaly protokol HTTPS. Moderní prohlížeče vyžadují zabezpečené připojení pro vkládání iframe.

✅ https://external-app.com/panel
❌ http://external-app.com/panel

Problémy se soubory cookie/relací

Problém: Ověřovací soubory cookie nefungují v iframech mezi zdroji

Řešení: Použijte SameSite=None; Secure pro soubory cookie, které musí fungovat v iframech, nebo implementujte ověřování na základě tokenů prostřednictvím parametrů URL.

Skripty pro rozbití rámce

Problém: Kód JavaScript zabraňuje vkládání iframe

Řešení: Odeberte nebo upravte skripty, které kontrolují window.top !== window.self nebo podobnou logiku pro rozbití rámce.

Responzivní design

Problém: Obsah se dobře nepřizpůsobuje omezením iframe

Řešení: Navrhněte rozvržení specifická pro iframe nebo použijte responzivní CSS, které dobře funguje v omezených prostorech. Zvažte nastavení velikosti panelu (tiny, small, medium, large).

Komunikace

Problém: Omezená komunikace mezi iframe a nadřazeným

Řešení: Použijte rozhraní API postMessage pro zabezpečenou komunikaci mezi zdroji, pokud vložený obsah potřebuje interagovat s nadřazenou aplikací.

Příklady konfigurace serveru

📝 Konfigurace domény — nahraďte {HOSTNAME} skutečnou doménou aplikace.

Apache (.htaccess):

Header always append X-Frame-Options "ALLOW-FROM {HOSTNAME}"
Header always set Content-Security-Policy "frame-ancestors 'self' {HOSTNAME}"
Header always set X-Content-Type-Options "nosniff"
Header always set X-XSS-Protection "1; mode=block"

Nginx:

add_header X-Frame-Options "ALLOW-FROM {HOSTNAME}" always;
add_header Content-Security-Policy "frame-ancestors 'self' {HOSTNAME}" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;

Node.js/Express:

app.use((req, res, next) => {
  res.setHeader('X-Frame-Options', 'ALLOW-FROM {HOSTNAME}');
  res.setHeader('Content-Security-Policy', "frame-ancestors 'self' {HOSTNAME}");
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-XSS-Protection', '1; mode=block');
  next();
});

💡 Testování kompatibility Iframe: Před nasazením otestujte externí adresu URL vytvořením jednoduchého souboru HTML s iframe odkazujícím na váš obsah. Otevřete jej v prohlížeči a zkontrolujte konzolu pro vývojáře, zda neobsahuje chyby související s rámcem.

Vlastní odkazy [badge:Links|info]

Odkazy na úrovni polí, které se zobrazují v polích editoru a otevírají externí aplikace s kontextovými daty

[try:/customLinks|Spravovat vlastní odkazy →|right]

K čemu jsou vlastní odkazy dobré?

Vlastní odkazy umožňují přidávat kontextové odkazy ke konkrétním polím v rozhraní editoru. Tyto odkazy mohou otevírat externí aplikace, prohledávat databáze nebo přecházet do souvisejících systémů, vše vyplněné daty z aktuálního záznamu.

• Přidejte odkazy přímo k popiskům polí, ikonám vedle vstupů nebo tlačítkům pod poli
• Otevřete externí aplikace s kontextem z aktuálního záznamu (např. jméno, ID, informace o uživateli)
• Odkazy jsou viditelné pouze v případě, že vybrané pole má hodnotu
• Podpora podmíněného zobrazení na základě výrazů filtru
• Respektujte omezení sady změn a režimu jen pro čtení

Běžné případy použití

🔗 Odkaz na systém CRM

Přidejte odkaz na pole jména zákazníka, který otevře záznam zákazníka ve vašem systému CRM.

🔍 Vyhledávání v databázi EAN

Přidejte odkaz na pole EAN pro vyhledání informací o produktu v externí databázi.

🛒 Otevřít v E-commerce

Přidejte odkaz pro zobrazení produktu v rozhraní vašeho e-commerce.

Pozice odkazů

Vlastní odkazy se mohou zobrazit ve třech různých pozicích vzhledem k poli:

Pozice popisku

Popisek pole se stane klikatelným odkazem. Po kliknutí se otevře externí URL. To je užitečné pro interaktivní celý popisek.

Pozice ikony

Malé tlačítko s ikonou se zobrazí za vstupním polem. Vedle sebe se může zobrazit více odkazů s ikonami. To je užitečné pro poskytnutí rychlého přístupu bez změny vzhledu pole.

Pozice pod

Odkaz se zobrazí jako malý textový odkaz pod vstupním polem. Více odkazů se může zalomit do více řádků. To je užitečné pro sekundární akce, které nepotřebují okamžitou viditelnost.

Konfigurační pole

Základní vlastnosti

• name — Text odkazu zobrazený uživatelům
• entityId — Cílová entita pro odkaz
• columns — Pole ID polí, kde by se měl odkaz zobrazit
• icon — Ikona zobrazená s odkazem (pro pozice ikony a pod)
• position — Kde zobrazit odkaz: “label”, “icon” nebo “under”

Konfigurace akce

• action — Typ akce (aktuálně je podporováno pouze “openUrl”)
• url — Cílová šablona URL s proměnnými zástupnými symboly

Podmíněné zobrazení

• condition — Volitelný výraz filtru pro zobrazení/skrytí odkazu
• allowInChangeSet — Zobrazit odkaz, když je aktivní sada změn
• allowInReadOnly — Zobrazit odkaz v režimu jen pro čtení

Proměnné šablony URL

URL může obsahovat zástupné symboly, které jsou nahrazeny skutečnými daty při kliknutí na odkaz:

Data záznamu

• {data.fieldName} — Hodnota libovolného pole z aktuálního záznamu (např. {data.name}, {data.ean})
• {objectIds} — ID aktuálního záznamu
• {entityId} — Identifikátor entity

Informace o uživateli

• {user.id} — ID aktuálního uživatele
• {user.username} — Uživatelské jméno aktuálního uživatele
• {user.email} — E-mailová adresa aktuálního uživatele

Informace o systému

• {language} — Kód aktuálního jazyka uživatelského rozhraní
• {orgId} — ID aktuální organizace

Příklad šablony URL:

https://crm.example.com/customer?name={data.name}&email={data.email}&lang={language}&user={user.username}

Pravidla viditelnosti

⚠️ Důležité: Požadavek na hodnotu pole

Vlastní odkazy jsou **viditelné pouze v případě, že přidružené pole má hodnotu**. Pokud je pole prázdné (null, undefined nebo prázdný řetězec), odkaz se nezobrazí, i když jsou splněny všechny ostatní podmínky.

Příklad podmíněného zobrazení

Můžete použít výrazy filtru k zobrazení odkazů pouze v případě, že jsou splněny konkrétní podmínky:

platform.code = 'shoptet'

Tento odkaz se zobrazí pouze v případě, že je produkt na platformě Shoptet.

Příklad konfigurace

Kompletní příklad vlastního odkazu:

{
  "name": "View in CRM",
  "entityId": "products",
  "columns": ["name", "ean"],
  "icon": "ExternalLink",
  "position": "icon",
  "action": "openUrl",
  "url": "https://crm.example.com/product?ean={data.ean}&name={data.name}&user={user.email}",
  "condition": "platform.code = 'shoptet' AND status = 'active'",
  "allowInChangeSet": false,
  "allowInReadOnly": true,
  "disabled": false
}

Tento odkaz se zobrazí jako ikona vedle polí “name” a “ean”, když je produkt na platformě Shoptet, je aktivní a pole má hodnotu. Otevře CRM s EAN produktu, jménem a e-mailem aktuálního uživatele.

💡 Doporučené postupy
- Použijte pozici ikony pro často používané odkazy, aby bylo uživatelské rozhraní čisté
- Použijte pozici popisku, když je odkaz primární akcí pro dané pole
- Použijte pozici pod pro sekundární nebo méně běžné akce
- Udržujte názvy odkazů krátké a popisné
- Otestujte šablony URL s různými daty záznamů, abyste zajistili, že fungují správně
- Použijte podmínky k zobrazení odkazů pouze v případě, že jsou relevantní
- Zvažte použití `allowInReadOnly=true` pro odkazy jen pro zobrazení

Barvy sloupců [badge:Colours|success]

Podmíněné barvy pozadí pro buňky datové mřížky

[try:/columnColours|Spravovat vlastní barvy →|right]

Klíčové vlastnosti

• Aplikujte barvy pozadí na buňky datové mřížky na základě podmínek filtru
• Cílit na všechny sloupce nebo konkrétní sloupce v entitě
• Pro každou entitu lze definovat více barevných pravidel
• Vyhodnocováno v reálném čase při změně dat
• Skvělé pro vizuální zvýraznění důležitých dat (např. položky po splatnosti, úrovně zásob)

Konfigurační pole

Základní vlastnosti

• name — Popisný název pro barevné pravidlo
• entityId — Cílová entita pro barevné pravidlo
• colour — Barva pozadí (hex formát, např. #ff0000)
• description — Volitelný popis pravidla

Filtrování

• filter — Podmínka podobná SQL, která určuje, kdy se má barva použít
  • Příklad: status = 'overdue' AND priority = 'high'

Cílení na sloupce

• allColumns — Použít barvu na všechny sloupce v řádku
• columns — Pole konkrétních názvů sloupců, které se mají obarvit (pokud je allColumns false)
  • Příklad: ["price", "discount", "total"]

Řízení

• disabled — Dočasně zakázat barevné pravidlo bez jeho odstranění

Případy použití

Zvýraznění stavu

Zvýrazněte řádky na základě hodnot stavu. Například zobrazte úkoly po splatnosti červeně, dokončené úkoly zeleně a úkoly ve stavu zpracování žlutě.

Příklad konfigurace:

Entita: tasks
Filtr: status = 'overdue'
Barva: #ffcccc (světle červená)
Všechny sloupce: true

Upozornění na prahové hodnoty

Zvýrazněte konkrétní sloupce, když hodnoty překročí prahové hodnoty. Například zvýrazněte sloupec zásob červeně, když zásoby klesnou pod minimální úroveň.

Příklad konfigurace:

Entita: products
Filtr: stock < minimumStock
Barva: #ff6666 (červená)
Všechny sloupce: false
Sloupce: ["stock"]

Vizualizace priority

Použijte různé barvy pro různé úrovně priority, abyste uživatelům pomohli rychle identifikovat položky s vysokou prioritou ve velkých datových sadách.

Příklad konfigurace:

Entita: orders
Filtr: priority = 'urgent'
Barva: #ffe6e6 (světle červená)
Všechny sloupce: true

Finanční ukazatele

Zvýrazněte finanční data na základě podmínek, jako jsou záporné zůstatky, nezaplacené platby nebo ziskové marže pod cílovými hodnotami.

Příklad konfigurace:

Entita: invoices
Filtr: balance < 0
Barva: #fff3cd (světle žlutá)
Všechny sloupce: false
Sloupce: ["balance", "status"]

Chování a priorita

Pořadí vyhodnocování

Barevná pravidla sloupců jsou vyhodnocována pro každý řádek v mřížce. Pokud více pravidel odpovídá řádku, použije se poslední odpovídající pravidlo (v pořadí, v jakém se zobrazují v databázi).

Aspekty výkonu

Barvy sloupců jsou vyhodnocovány v reálném čase při změně dat. Udržujte výrazy filtru jednoduché a efektivní pro nejlepší výkon, zejména u velkých datových sad.

Zakázaná pravidla

Použijte pole disabled k dočasnému vypnutí barevných pravidel bez jejich odstranění. To je užitečné pro testování nebo sezónní úpravy.

💡 Doporučené postupy
- Používejte jemné barvy, které nezasahují do čitelnosti textu
- Omezte počet barevných pravidel na entitu, abyste se vyhnuli vizuálnímu nepořádku
- Otestujte barevné kombinace pro přístupnost (poměry kontrastu)
- Dejte pravidlům popisné názvy, abyste je mohli později udržovat
- Zvažte preference uživatelů - někteří uživatelé mohou být barvoslepí

Poznámky k implementaci

Výkon

Úpravy jsou načítány a filtrovány efektivně pomocí React hooks se správnou správou závislostí a atomickými aktualizacemi stavu, aby se zabránilo blikání uživatelského rozhraní.

Zabezpečení

Všechny úpravy respektují základní systém oprávnění a řízení přístupu k entitám. Uživatelé mohou vidět a interagovat pouze s úpravami pro entity, ke kterým mají přístup.