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.

Project folder structure example

├── 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:

components/component-name.json

{
  "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:

components/component-name.json

{
  "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:

components/component-name.json

...

  "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 a querySelector to target a sub-node within the component.
  • classes is the list of CSS classes that will be toggled when this preset will be selected.

About Selector

You can use any type of complex CSS selector, here are common examples.

• #id
• tag
• .class
• [attribute]
• self (refers to the selector containing data-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:

components/component-name.json

...

  "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-control
    • name is the name of the CSS style.
    • value is the actual CSS class or CSS 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 with ui-colorgroup control) is the CSS class or color value that will be used for previewing the style in the visual editor.

About Selector

You can use any type of complex CSS selector, here are common examples.

• #id
• tag
• .class
• [attribute]
• self (refers to the selector containing data-pf)

For the full reference list of CSS Selector, go check that W3schools.com page

About Value

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