Vysvetlenie súboru a formátu components.json

Všeobecný formát

Nižšie je uvedený všeobecný formát súboru components.json:

• V rámci každého komponentu sú určené vlastnosti daného komponentu. Vlastnosti "components" a "apps" najvyššej úrovne sú zastarané.

• Každý komponent má vlastnosť "type". Komponenty môžu mať len určité hodnoty (všetky možné hodnoty sú uvedené v tabuľke predvolených komponentov).

• Každý komponent má vlastnosť "id", ktorá musí byť jednoznačná. Táto vlastnosť sa používa na rozlišovanie medzi komponentmi s rovnakou vlastnosťou "type". V minulosti mali aplikácie vlastnosť "appName". Aj keď vlastnosť "appName" naďalej funguje, keď nie je k dispozícii vlastnosť "id", vlastnosť "appName" je zastaraná.

• Každý komponent má vlastnosť "name", ktorá predstavuje zobrazovaný názov v používateľskom rozhraní. Ak nie sú zadané rezervné hodnoty, v prípade komponentov je hodnotou názov zodpovedajúceho predvoleného komponentu, zatiaľ čo v prípade vzdialených komponentov je hodnotou ID.

Nižšie je uvedený príklad súboru components.json:

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                ...
            },
            {
                ...
            },...
        ]
    },
    {
        "name": "My own category name",
        "list": [ ... ]
    }
]

Všeobecnou štruktúrou je pole JSON objektov kategórií. Každý objekt kategórie má vlastnosti "name" a "list". Vlastnosť "name" môže byť kľúčom mapovaným k lokalizovanému reťazcu. Ak tieto predvolené kategórie nie sú dostatočné, môžete zadať vlastný názov kategórie, ktorý nebude lokalizovaný. Nasledujúca tabuľka obsahuje dostupné predvolené kategórie a zodpovedajúce kľúče.

Vlastnosť "list" v jednotlivých objektoch kategórií obsahuje pole objektov komponentov. Každý komponent alebo objekt musí mať vlastnosti "type" a "id". Ostatné vlastnosti sú voliteľné.

• Vlastnosť "type" musí byť rovnaká ako jeden z typov uvedených v predvolených komponentoch. Ak ešte vlastnosť "type" neexistuje, komponent sa nezobrazí.

• Vlastnosť "id" musia mať všetky komponenty jednoznačnú. Ak sa zistí, že vlastnosť "id" už existuje, komponent sa nezobrazí.

• Vlastnosť "name" je zobrazovaným názvom komponentu v používateľskom rozhraní. V prípade aplikácií (teraz vzdialených komponentov) nahrádza predchádzajúcu vlastnosť "appName".

• Všetky ostatné vlastnosti sa spracúvajú rovnako ako v predchádzajúcich vydaniach.

Pridanie nových komponentov do súboru components.json

Predvolené komponenty nemôžete modifikovať. V prípade potreby však môžete vytvoriť nový komponent založený na existujúcom predvolenom komponente. Môžete napríklad vytvoriť nový komponent založený na komponente "scs-title", ktorý nastavuje predvolený text. Pri pridávaní nového komponentu je potrebné určiť aspoň vlastnosti "type" a "id".

• Vlastnosť "type" musí byť rovnaká ako jeden z typov uvedených v predvolených komponentoch. Ak ešte vlastnosť "type" neexistuje, komponent sa nezobrazí.

• Vlastnosť "id" musia mať všetky komponenty jednoznačnú. Ak sa zistí, že vlastnosť "id" už existuje, komponent sa nezobrazí.

Nižšie je uvedený príklad kódu použitého na pridanie nového komponentu nadpisu. Tento komponent sa zobrazí spolu s predvoleným komponentom nadpisu.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline"
            }
        ]
    }
]

Nižšie je uvedený príklad kódu použitého na pridanie nového komponentu nadpisu so zobrazovaným názvom a predvoleným textom.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                "initialData": {
                    "userText": "This is a second title component"
                }
            }
        ]
    }
]

Komponent nadpisu preberá všetky vlastnosti predvoleného komponentu nadpisu, ktoré sa používajú ako základ. Okrem týchto vlastností sa aplikujú modifikácie na úrovni motívu, čím vzniká nový komponent.

Spätná kompatibilita

Súbory components.json v predchádzajúcom formáte možno naďalej čítať.

• Súbory s vlastnosťou "components" alebo "apps" najvyššej úrovne.

• Ak súbor obsahuje vlastnosť "apps", naďalej sa načítajú používateľom definované vzdialené komponenty v rámci tejto vlastnosti.

• Ak súbor obsahuje vlastnosť "apps" najvyššej úrovne, predpokladá sa, že všetky vzdialené komponenty uvedené nižšie sú typu "scs-app".

• Ak existuje vlastnosť "appName", nastavte vlastnosť "id" na hodnotu "appName". Zobrazovaný názov bude rovnaký ako vlastnosť "name" (ak je zadaná), prípadne sa použije hodnota vlastnosti "id".