Skip to main content

Get Started - Tutorial

Create a Theme

To use Section Designer and Component Designer features, you need first to create a theme.json configuration file, sync it with our CLI and link it to your preview site. Follow those steps to create your first theme.json

tip

You may skip this step if you are not planning to use Section Designer and Component Designer features.

Install CLI​

First, you will need to install the CLI in order to synchronize the created configuraitons to the Perfection application.
For a detailed description on how to install the CLI, read this document.

To install the CLI globally through NPM, you can run the following command.

>_ Terminal
npm install -g @perfectiondev/cli

Configure API Key​

Before using any commands from our CLI, you first need to create a file with your Perfection's API Key and Subscription ID. Please read this guide to see how you can create a file to store your credentials.

Scaffold Theme.json​

To start with a clean theme configuration, you can use the theme create command to scaffold a new .json configuration file.

Run the following CLI command in your terminal to scaffold a Theme or grab this theme.json example from Github

>_ Terminal
perfection app theme create -f theme.json

Update Theme config​

Once you have your theme config file, you need to populate it with the settings as you would like to have them.

theme.json
{
  "name": "My Theme",
  "key": "my-theme-key",
  "description": "My theme description",
  "componentFolders": ["./components/"],
  
  "decorations": [
    {
      "name": "Decoration 1",
      "class": "dark-decoration"
    },
    {
      "name": "Decoration 2",
      "class": "light-decoration"
    }
  ],

  "layouts": {
    "prebuilt": [
      "col_100",
      "col_50_50",
      "grid_2s_1l"
    ],
    "custom": [
      {
        "name": "20:80",
        "category": "grid",
        "description": "20% and 80% width",
        "class": "custom-20-80"
      }
    ]
  }
}

Above configuration will create a Theme with two Decorations (the colors orange and indigo), uses 3 prebuilt Layouts and defines 1 custom Layout.

Define Components config​

Within the ./components/ folders you defined in the theme configuration, you can create JSON files for each of you components. Each component definition follows the following syntax.

Take the below JSON as an example or grab this Github example

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"
            }
          ]
        }
      ]
    }
  ]
}

Above configuration reflects a "Grid Card" component with a Headline and an Image, both with color based options.

Sync Theme and Components​

Now it is time to synchronize the theme details, decorations and layouts, components with your Perfection account. You do this by using the CLI app theme sync command in your Terminal:

>_ Terminal
perfection app theme sync -f theme.json

Once ran successfully, this is what you should see in your Terminal:

>_ Terminal
USER perfection-cli (main) >> perfection app theme sync -f theme.json
  ✔ Validate prerequisites
  ✔ Read theme
  ✔ Validate
  ✔ Sync theme details
  ✔ Sync theme decorations and layouts
  ✔ Sync components
note

You should also see the newly created Theme in your Admin Panel, under the Themes tab.

Developers Ressources​