Atributy

Nastavení atributů v administraci — Nastavení > Atributy & Tagy

Definice

Atributy jsou konfigurovatelný sloupcový systém, na kterém stojí každá tabulka a detailní zobrazení v TWICE. Cokoli, co tvůj byznys potřebuje sledovat a co není v jádru datového modelu, vyjádříš přes atributy: stupeň stavu, sériové číslo, datum začátku záruky, vlastní pokyny pro doručení.

Analogie: Atributy se chovají jako vlastní sloupce v tabulce: definuješ je jednou a pak se objevují v tabulkách, formulářích, filtrech i exportech.

Kde se atributy uplatňují

Každý atribut je vázán přesně na jeden zdroj:

Zdroj	Platí pro
`inventory`	Skladové položky a SKU, ke kterým se sčítají
`catalog`	Inzeráty
`customers`	Profily zákazníků
`orders`	Objednávky

Stejný atribut nelze použít napříč více zdroji: pokud potřebuješ podobná pole u zákazníků i objednávek, definuješ je zvlášť. Tím zůstává schéma každého zdroje čisté a nedochází k prolínání mezi zdroji. Atributy zásob mohou mít jeden ze dvou původů:

sku – atribut je definovaný na úrovni SKU a dědí ho každá skladová položka pod tímto SKU
article – atribut je definovaný jen na úrovni skladové položky (skladové položky se interně nazývají také Articles)

Toto rozdělení ti umožní vyjádřit „Značku“ jednou na SKU a „Sériové číslo“ jednotlivě u každé skladové položky, aniž bys pole duplikoval(a).

Formáty atributů

TWICE podporuje osm formátů atributů:

Formát	Případ užití	Uloženo jako
`text`	Krátké popisky, identifikátory, poznámky: volitelně omezené přijímanými formáty	Řetězec
`number`	Měřitelné hodnoty: hmotnost, rozměry, kapacita	Číslo
`boolean`	Příznaky Ano / Ne	Boolean
`date`	Kalendářní data bez časové složky	Datum ve formátu ISO 8601
`datetime`	Přesná časová razítka	Datum a čas ve formátu ISO 8601
`select`	Jedna volba z definovaného seznamu možností	Řetězec (`key` dané možnosti)
`multiselect`	Více voleb ze seznamu možností	Pole řetězců
`formula`	Hodnota vypočtená z jiných atributů a systémových polí	Výraz jako řetězec

Formát také určuje, kde lze atribut sbírat. Pole placení inzerátu typu Atribut zákazníka přijímá jen text, number, boolean, date a datetime, protože ostatní tři na tomto kroku nemají žádný vstup. Krok pokladny Kontakt vykresluje každý formát kromě formula. Neexistuje samostatný formát currency, percent, email, url, phone, file, relation ani external: pro měnu a procenta použij number, pro e-maily a URL adresy text a pro přílohy souborů Dokumenty. Atribut typu text může svou přijímanou hodnotu omezit přijímanými formáty, které popisují pevný tvar, jako je číslo karty nebo licence. Formáty nevyjádří otevřené tvary, jako je e-mailová adresa.

Možnosti pro select a multiselect

Každá možnost u atributu typu select nebo multiselect je dvojice { key, label }:

[
  { "key": "good", "label": "Dobrý" },
  { "key": "fair", "label": "Uspokojivý" },
  { "key": "needs-repair", "label": "Vyžaduje opravu" }
]

key je neměnný identifikátor uložený na záznamech. label je to, co vidí uživatelé, a lze ho volně upravovat, aniž by se rozbila historická data. Obě pole mají limit 255 znaků.

Vzorcové atributy

Vzorcové atributy počítají svou hodnotu z jiných polí na stejném zdroji. Každý zdroj vystavuje jinou sadu systémových polí, na které se vzorce mohou odkazovat:

Zdroj	Systémová pole dostupná ve vzorcích
Zákazník	`created_at`, `first_name`, `last_name`, `phone`, `email`, `marketing_consent`, `language`
Zásoby	`created_at`, `name`, `code`, `item_costs`, `item_income`
Katalog	`created_at`, `name`, `status`, `description`

Typický vzorec kombinuje tato systémová pole s dalšími atributy: vzorec skladové položky item_income - item_costs například dává průběžný zisk. Vzorec se přepočítá pokaždé, když se změní jeho vstupy. Přečti si více: Vzorce

Přijímané formáty

Atribut typu text může nést přijímané formáty: šablonové řetězce popisující přesný tvar, který hodnota může mít, jako 123456 #### ######[#] pro číslo členské karty. Hodnota, která neodpovídá žádnému z formátů atributu, je odmítnuta. Každý formát zároveň řídí tři věci: validační pravidlo, které aplikuje server, placeholder, který vidí zákazník, a formátování, které vstup aplikuje za psaní. Všechny tři vycházejí ze stejného formátu, takže si nemohou odporovat. Formáty platí jen pro text. Upravuješ je v panelu atributu pod Nastavení → Atributy & tagy, kde je sekce označená Přijímané formáty. Odkaz „Přečti si, jak formáty fungují“ otevře referenci syntaxe. Každý řádek zobrazuje vyplněný příklad a přijímanou délku hodnoty, takže je posun o jedno místo v nepovinném bloku vidět dřív, než uložíš.

Panel atributu se zadaným formátem, zobrazující vyplněný příklad a přijímanou délku hodnoty — Nastavení > Atributy & tagy: editor Přijímané formáty

Syntaxe formátu

Vše ve formátu je pevný text, pokud nejde o jeden z těchto symbolů:

Symbol	Odpovídá
`#`	Jedna číslice, `0`–`9`
`@`	Jedno písmeno v libovolné abecedě: `ä`, `ö`, `å` i `Ç` se počítají
`*`	Jedno písmeno nebo číslice
`{abc}`	Jeden znak, který musí být jedním z uvedených
`[…]`	Nepovinné zakončení, které zákazník může vynechat: přítomné celé, nebo chybějící
`\`	Označí další znak jako doslovný, pro znak `#`, `@`, `*`, `{`, `}`, `[`, `]` nebo `\`

Pevný text se porovnává a vykresluje přesně tak, jak jsi ho zadal(a), včetně mezer a pomlček. 123456 #### je šest pevných číslic, mezera a poté čtyři pozice pro číslice: úvodní číslice se nikdy nečtou jako pozice k vyplnění. Editor navíc vynucuje pár pravidel:

{…} vyjmenovává své členy doslovně. Rozsahy neexistují: {1-3} přijme 1, - nebo 3, ne 1 až 3. Shoda je přesná na velikost písmen, takže {AB} odmítne a.
Formát smí obsahovat nejvýše jeden nepovinný blok, a musí být na konci.
Formát potřebuje aspoň jednu vstupní pozici: #, @, * nebo {…}.
Sada znaků nesmí být prázdná, vnořená ani opakovat stejný znak.

Dialog Jak formáty fungují se seznamem symbolů formátu a řešenými příklady — Přečti si, jak formáty fungují: referenční dialog v aplikaci

Řešené příklady, s délkou hodnoty, kterou editor uvádí u každého formátu:

Formát	Přijímá	Délka
`####`	`1234`	4
`@@-####`	`AB-1234`	6
`CARD-####`	`CARD-1234`	8
`{ABC}-###`	`A-123`, `C-456`	4
`123456 #### ######[#]`	`123456 1140 411905`, `123456 1140 4119051`	16–17
`#####[-####]`	`12345`, `12345-6789`	5–9

Délka počítá hodnotu tak, jak ji čteš na kartě: pevné znaky se počítají, oddělovače ne, ne počet znaků, které zákazník napíše.

Více přijímaných formátů

Atribut může přijímat více tvarů. Přidej jeden formát na tvar, až 10 formátů, každý nejvýše 100 znaků. Formáty v seznamu musí jít rozeznat podle svých pevných začátků, porovnaných bez oddělovačů. TWICE odmítne seznam, kde je pevný začátek jednoho formátu prefixem jiného: 123456 #### a 998877 #### jsou v pořádku, @@@-### a @@@### ne, protože ani jeden nemá pevný začátek, podle kterého by se odlišil. Chyba pojmenuje oba formáty, které kolidují. Chování pole závisí na tom, kolik formátů atribut má:

Formáty	Chování
Jeden	Pevný začátek se zákazníkovi vyplní, jakmile pole zaměří, takže píše jen svou část. Pokud pole opustí bez psaní, vyprázdní se zpět. Placeholder ukazuje daný jeden formát.
Více	Nic se nepředvyplňuje: první napsaný znak vybere formát a pole se od něj formátuje. Placeholder vyjmenuje všechny přijímané formáty.

Hodnota, která neodpovídá žádnému formátu, zůstává za psaní jako volný text, místo aby se dotlačila do nejbližšího tvaru, a při odeslání je odmítnuta.

Kde se formáty vynucují

Formáty nikdy nedělají pole povinným. Prázdná hodnota vždy projde: přítomnost řídí samostatně nastavení pole Povinné.

Pokladna ve výkladní skříni – pole vázaná na atribut na kroku Kontakt a na kroku Další podrobnosti se formátují, jak zákazník píše, vyplní pevný začátek a normalizují hodnotu vloženou bez oddělovačů. Chybně vyplněná hodnota krok zablokuje.
Administrace – stejný maskovaný vstup platí všude, kde personál zadává hodnoty atributů, včetně panelu zákazníka a polí placení na nové objednávce.
API a server – každý zápis hodnoty atributu typu text se validuje. Odpověď je 400 s názvem atributu a vyplněným příkladem každého přijímaného formátu: Member card: must match the format 123456 1234 567890. Při potvrzení pokladny server znovu kontroluje kontaktní atributy a chybně vyplněné hodnoty hlásí odděleně od chybějících povinných.

Hodnoty se porovnávají v zobrazované podobě, včetně pevných znaků. Pošli "123456 1140 411905", ne "1234561140411905": vstup ve výkladní skříni normalizuje vložené hodnoty, API ne.

Krok Kontakt v pokladně výkladní skříně s polem Členská karta, které zobrazuje vyplněný pevný začátek a naformátované napsané číslice — Pole s maskovaným atributem v pokladně, uprostřed zadávání

Změna formátů

Formáty patří k typu text. Změna formátu atributu na cokoli jiného je vymaže.
Přidání nebo úprava formátu validuje hodnoty zapsané od té chvíle. Už uložené hodnoty zůstávají nedotčené a znovu se nekontrolují.
Odstraněním všech formátů se pole znovu stane neomezeným.

Klíčové vlastnosti

Definice atributu nese:

Vlastnost	Typ	Popis
`id`	UUID	Stabilní identifikátor
`key`	Řetězec	Strojově čitelný identifikátor použitý v API a exportech: opravuje se při zápisu, viz Jak je uložen klíč
`name`	Řetězec	Zobrazovaný název (např. „Stav“)
`description`	Řetězec	Volitelný nápovědný text zobrazený ve formulářích
`format`	Enum	Jeden z osmi formátů výše
`valueOptions`	Pole	Dvojice `{ key, label }` pro select/multiselect, jinak `null`
`valueMasks`	Pole	Přijímané formáty pro atributy typu `text`; `null`, když pole není omezené
`formula`	Řetězec	Výraz pro vzorcové atributy
`resource`	Enum	`inventory`, `catalog`, `customers`, `orders`
`groupId`	UUID	Volitelná skupina atributů, do které atribut patří
`systemGroup`	Enum	`system` (zákazník) pro systémově spravované skupiny
`sortOrder`	Číslo	Pozice ve skupině
`global`	Boolean	Zda je atribut systémově definovaný (true), nebo definovaný nájemcem (false)

Systémové skupiny jsou vyhrazené kategorie – system pro zákazníka – které drží atributy spravované TWICE tvým jménem.

Jak je uložen klíč

Uložený key obsahuje malá písmena, číslice, _ a -, a nic jiného. TWICE Commerce to, co napíšeš, opravuje místo toho, aby to odmítal: pole Klíč atributu v panelu přidání/úpravy atributu přepisuje tvůj vstup za psaní, takže pole vždy zobrazuje hodnotu, která se uloží. Nápovědný text říká totéž – „Malá písmena, čísla, - a _. Cokoli jiného se automaticky převede.“ Oprava proběhne v tomto pořadí:

Velká písmena se převedou na malá.
Mezery se změní na _.
Každý zbývající znak mimo a-z, 0-9, _ a - se odstraní.
Úvodní attributes_ se odstraní.

Napíšeš	Uloží se jako
`piece_size`	`piece_size`
`Cut Style`	`cut_style`
`list-CutStyle`	`list-cutstyle`
`Manufacturer's SKU (v2)`	`manufacturers_sku_v2`
`attributes_color`	`color`
`***`	nic nepřežije: klíč se vrátí k názvu atributu

Klíč nech prázdný, nebo napiš něco, po čem nic použitelného nezůstane, a TWICE Commerce odvodí klíč z name atributu podle stejných pravidel. Odvozený klíč, který je už obsazený, dostane číselnou příponu – condition, pak condition_1, condition_2. Klíč, který sis napsal(a) sám/sama, se ti nikdy nepřejmenuje. Pokud koliduje s atributem, který už existuje, uložení selže se zprávou Attribute key "condition" is already in use. a vybereš jiný. Přejmenování klíče později prochází stejnou opravou. Přejmenování, po kterém nic použitelného nezůstane, se bere jako žádné přejmenování: uložený klíč zůstane, jaký byl, místo aby se vyprázdnil.

API přijme jako key libovolný řetězec a při zápisu ho opraví, takže hodnota, kterou přečteš zpět, se může lišit od hodnoty, kterou jsi poslal(a) – pošli key s hodnotou list-CutStyle a atribut se vytvoří s list-cutstyle. Uložený klíč přebírej z odpovědi, ne z hodnoty, kterou jsi poslal(a).

Dědičnost: SKU > skladová položka

Konkrétně pro atributy zásob:

Atribut s origin: sku je definovaný na SKU a čte se na každé skladové položce, která se k tomuto SKU sčítá
Atribut s origin: article je definovaný přímo na skladové položce a nesdílí se se sourozeneckými položkami
Úprava atributu s původem na SKU na jedné skladové položce není povolená: upravuješ ho na SKU a změna se propíše

To znamená, že atributy SKU fungují jako „šablona“ pro jeho skladové položky, a každá skladová položka ukládá jen hodnoty, které se liší kus od kusu (sériové číslo, stav, umístění, datum nákupu).

Atributy objednávky

Atributy vázané na orders připojují vlastní data k jednotlivým objednávkám, ne k zásobám, katalogu ani záznamům zákazníka. Časté příklady: nákladové středisko, dárkový vzkaz, číslo objednávky (PO), nebo zvláštní pokyny pro doručení.

Zachycení v pokladně

Přidej pole atributu do kontaktního formuláře pokladny a přiřaď ho k atributu. V pokladně systém směruje zachycenou hodnotu podle zdroje atributu:

orders – uloží se do hodnot atributů objednávky
customers – uloží se do profilu zákazníka

To znamená, že stejný formulář pokladny může v jednom kroku sbírat data specifická pro objednávku i pro profil zákazníka.

Potvrzovací e-mail

Zachycené hodnoty atributů objednávky se automaticky vykreslí v potvrzovacím e-mailu objednávky:

Globální atributy objednávky se zobrazí vždy, s pomlčkou jako zástupným symbolem, když hodnota nebyla zachycena
Neglobální atributy objednávky se zobrazí jen tehdy, když hodnota existuje

Hodnoty se formátují podle lokalizace tvého nájemce: data používají tvůj nastavený formát data, select atributy zobrazují label možnosti a boolean hodnoty se vykreslí jako Ano/Ne, hodnoty multiselect jsou oddělené čárkou.

Administrace

Hodnoty atributů objednávky se zobrazují na detailní stránce objednávky ve vyhrazené kartě atributů. Hodnoty můžeš přímo přidávat, upravovat i odstraňovat. Atributy objednávky se také zobrazují jako filtrovatelné, řaditelné sloupce v tabulce objednávek.

Filtrování a vyhledávání

Jakmile atribut existuje, automaticky se objeví v tabulce svého zdroje:

Chování	Detail
Sloupec	Nový sloupec v tabulce zdroje, ve výchozím stavu skrytý: zobrazíš ho přes ovládání sloupců
Filtr	Operátor filtru závisí na formátu: `equals`, `contains`, `is any of`, `before`, `after`, `is null` atd.
Řazení	Všechny neformulové formáty jsou řaditelné
Seskupení	Atributy typu boolean, select a date seskupují řádky v tabulce
Vyhledávání	Atributy typu text a number odpovídají vyhledávání v panelu nástrojů
Export	Viditelné sloupce atributů se zahrnou do exportu CSV

Vyhledávání je fulltextové a prohledává všechny hodnoty atributů převoditelné na řetězec, takže vyhledávání v panelu nástrojů najde shody i ve skrytých sloupcích.

Přístup přes API

Atributy se objevují v každé API odpovědi zdroje, na který se vztahují. Jsou klíčované podle id a vystavené jako typovaný záznam hodnot. Typická odpověď zásob zahrnuje:

{
  "id": "stk_abc123",
  "skuId": "sku_xyz789",
  "attributes": {
    "attr_color": "Navy",
    "attr_condition": "good",
    "attr_serialNumber": "BK-2024-0011",
    "attr_purchasePrice": 89.00
  }
}

Hodnoty u select atributů jsou key možnosti, ne uživatelsky viditelný label.

Životní cyklus

Vytváření

Otevři Nastavení → Atributy & tagy
Vyber zdroj, na který se atribut vztahuje (Zásoby, Katalog, Zákazník, Objednávka)
Nastav název, popis a formát
Pro select / multiselect definuj seznam možností
Pro text volitelně přidej jeden nebo více přijímaných formátů: viz Přijímané formáty
Pro formula napiš výraz a vyber výsledný formát
Volitelně přiřaď skupinu a pořadí řazení

Aktualizace

Název, popis, pořadí řazení a skupinu lze měnit volně
Přidání dalších možností do select/multiselect je bezpečné
Přejmenování label u možnosti je bezpečné: uložený je podkladový key
Odstranění možnosti rozbije každý záznam, který na ni odkazoval: TWICE před tím varuje
Přidání nebo úprava přijímaného formátu platí pro hodnoty zapsané od té chvíle; už uložené hodnoty se znovu nekontrolují
Změna formátu je omezená, protože konverze může ztratit data; bezpečnější vzor je vytvořit nový atribut a přenést hodnoty. Přesun atributu typu text na jiný formát vymaže jeho přijímané formáty

Archivace a smazání

Archivace skryje atribut pro nové zadávání, ale zachová historické hodnoty
Smazání odstraní definici atributu a všechny uložené hodnoty pro něj napříč každým záznamem; nedá se vrátit zpět
Archivaci používej téměř vždy; smazání si nech pro úklid omylem vytvořených atributů

Vztahy

Časté dotazy

Můžu použít stejný atribut na skladových položkách i inzerátech?

Ne: každý atribut je vázaný na jeden zdroj. Pokud potřebuješ paralelní pole, vytvoř odpovídající atributy na každém zdroji.

Jaký je rozdíl mezi atributem s původem na SKU a s původem na skladové položce?

Atributy s původem na SKU jsou definované jednou na SKU a čtou se na každé skladové položce pod ním (např. značka). Atributy s původem na skladové položce jsou jedinečné pro jeden fyzický kus (např. sériové číslo). Původ zvol podle toho, jestli se hodnota liší kus od kusu.

Můžu po zavedení měnit možnosti u select atributu?

Přidávání možností je bezpečné. Přejmenování uživatelsky viditelného label možnosti je bezpečné: podkladový key zůstává. Smazání možnosti rozbije každý záznam, který na ni odkazoval, takže TWICE před tím varuje.

Můžu omezit, co atribut typu text přijímá?

Ano: přidej mu jeden nebo více přijímaných formátů. Formát popisuje pevný tvar (123456 #### ######[#]) a hodnota musí odpovídat jednomu z formátů, které atribut nese. Formáty se hodí na identifikátory jako číslo karty, licence nebo členství; nevyjádří otevřené tvary, jako je e-mailová adresa.

Jak se aktualizují vzorcové atributy?

Vzorce se přepočítají pokaždé, když se změní jejich vstupní pole: bez ručního obnovení. Výsledek je jen ke čtení.

Jsou atributy viditelné pro zákazníky?

Ve výchozím stavu ne. Zda se atribut zobrazí ve výkladní skříni, závisí na konfiguraci tématu tvé výkladní skříně: témata si volí, které atributy vykreslují na stránkách inzerátu.

Můžu atributy hromadně upravovat?

Ano. Vyber řádky v libovolné tabulce a zvol Upravit: tlačítko počítá tvůj výběr, takže u tří řádků zobrazí Upravit (3), poté nastav nové hodnoty pro libovolný viditelný sloupec atributu.

Reference pro vývojáře

Atributy jsou v API vystavené jako attributes.

API: Attributes

Otevřít koncový bod v referenci API.

Související články

Skupiny atributů

Seskup příbuzné atributy pro přehlednější formuláře

Vzorce

Napiš výrazy pro vypočítávané atributy

Taxonomie kategorií

Kategorie doporučují atributy: fungují spolu

Tabulky

Kde se atributy zobrazují jako filtrovatelné sloupce

Vítejte v dokumentaci TWICE

Orientace v TWICE

Jak systém funguje

Definice

Kde se atributy uplatňují