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
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.
- Npm
- Yarn
- Pnpm
- Bun
npm install -g @perfectiondev/cli
yarn global add @perfectiondev/cli
pnpm i -g @perfectiondev/oversite-helpers
bun add -g @perfectiondev/oversite-helpers
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
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.
{
"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
{
"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
:
perfection app theme sync -f theme.json
Once ran successfully, this is what you should see in your 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
You should also see the newly created Theme in your Admin Panel, under the Themes tab.