Developers - CLI and Themes
component.json
This file contains presets
and styles
configuration available for a given component. It is essential to store them for each component in individual files. This practice enhances the maintability of your project by keeping component-specific settings distinct and easily accessible.
Files structure
These files should be placed within the ./components/
directory, as specified in your theme.json
configuration file.
├── root
│ ├── perfection
│ │ ├── theme.json
│ │ ├── perfection.json
│ │ ├── components
│ │ │ ├── promo-bar.json
│ │ │ ├── hero-banner.json
│ │ │ ├── product-card.json
│ │ │ ├── ...
Here is an example of a component configuration file with multiple Styles and Presets:
{
"name": "My Component",
"key": "my-component-key",
"description": "My component description",
"presets": [
{
"name": "Default",
"key": "default-preset-key",
"preview": null,
"default": true,
"elements": [
{
"selector": "self",
"classes": "ui-product-card"
},
{
"selector": "[data-selector='banner']",
"classes": "ui-product-card__banner"
}
]
},
{
"name": "Classic",
"key": "classic-preset-key",
"preview": "/presets/classic.png",
"elements": [
{
"selector": "self",
"classes": "ui-product-card ub-ps-classic"
},
{
"selector": "[data-selector='banner']",
"classes": "ui-product-card__banner bg-black"
}
]
}
],
"elements": [
{
"name": "Text",
"selector": "div > p",
"properties": [
{
"name": "Color",
"ui": "ui-colorgroup",
"values": [
{
"name": "Black",
"value": "tx-black",
"display": "#000"
},
{
"name": "Gold",
"value": "tx-gold",
"display": "#ba933e"
}
]
}
]
},
{
"name": "Background",
"selector": "div",
"properties": [
{
"name": "Color",
"ui": "ui-colorgroup",
"values": [
{
"name": "Dark",
"value": "bg-dark",
"display": "#000"
},
{
"name": "Light",
"value": "bg-light",
"display": "#ba933e"
}
]
}
]
}
]
}
JSON schema
Metadata
The first thing you need to define are the component's metadata information. Each component must have a unique name and key and a short description:
{
"name": "My Component",
"key": "my-component-key",
"description": "My component description",
"presets": [...],
"elements": [...]
}
Presets
The presets
path represent an array of objects, containing informations about presets with a list of selectors and classes that will be toggled when selecting the preset via the visual editor.
The following example shows 2 presets. A first one called Default and a second one called Classic:
...
"presets": [
{
"name": "Default",
"key": "default-preset-key",
"preview": null,
"default": true,
"elements": [
{
"selector": "self",
"classes": "ui-product-card"
},
{
"selector": "[data-selector='banner']",
"classes": "ui-product-card__banner"
}
]
},
{
"name": "Classic",
"key": "classic-preset-key",
"preview": "/presets/classic.png",
"elements": [
{
"selector": "self",
"classes": "ui-product-card ub-ps-classic"
},
{
"selector": "[data-selector='banner']",
"classes": "ui-product-card__banner bg-black"
}
]
}
]
...
name
is the display-name the preset will have in the visual editor.key
is the unique identifier the preset will have in our system.preview
(optional) is anrelative path to your public folder linking to an image that will be used as preview in the visual editor.elements
is an array of objects containing all the presets' selectors:selector
is aquerySelector
to target a sub-node within the component.classes
is the list ofCSS classes
that will be toggled when this preset will be selected.
You can use any type of complex CSS selector, here are common examples.
#id
tag
.class
[attribute]
self
(refers to the selector containingdata-pf
)
For the full reference list of CSS Selector, go check that W3schools.com page
Styles
The elements
path represent an array of objects, containing all the individual styles that can be toggled by business users via the visual editor:
...
"elements": [
{
"name": "Text",
"selector": "div > p",
"properties": [
{
"name": "Color",
"ui": "ui-colorgroup",
"values": [
{
"name": "Black",
"value": "tx-black",
"display": "#000"
},
{
"name": "Gold",
"value": "tx-gold",
"display": "#ba933e"
}
]
}
]
}
],
...
name
is the display-name of a group of styles.selector
is a querySelector to target a node within the component.properties
is an array of objects containing all the styles for the current group:name
is the value displayed for the style in the visual editor.ui
is the visual editor control you want for this style. Full list underneath.values
is an array of objects containing the CSS styles available in the selected ui-controlname
is the name of the CSS style.value
is the actualCSS class
orCSS variable
that will be injected in the DOM if selected.pf-none
should be used to create an option equivalent to "none/no selection"display
(only used withui-colorgroup
control) is theCSS class
orcolor value
that will be used for previewing the style in the visual editor.
You can use any type of complex CSS selector, here are common examples.
#id
tag
.class
[attribute]
self
(refers to the selector containingdata-pf
)
For the full reference list of CSS Selector, go check that W3schools.com page
If you want an option to be "none" (as in: no selection), set value
to pf-none
.
This tells our script to remove any of the other values from the array of values from the target DOM-node.
UI controls
Name | Screenshot | Key |
---|---|---|
Button Group | ui-buttongroup | |
Color Group | ui-colorgroup | |
Dropdown | ui-dropdown | |
Decoration | ui-decoration | |
Font List | ui-fontlist | |
Icon Group | ui-icongroup | |
Icon List | ui-iconlist | |
Number | ui-number | |
Position | ui-position | |
Range | ui-range |