In this tutorial we’ll explore the stencil theme editor the two main files will work with our config.json which we’ve seen in earlier posts and schema dodging schema dodging declares which theme settings are editable in the theme editor while config.json assigns and updates a default value for each of these editable settings first you’ll want to have your theme up in your IDE of choice as well as the local storefront to launch your theme in theme editor view use the command stencil start – e – pull up the storefront you want to go to localhost 8181instead of local who is 3000.
Let’s look at the structure of the theme editor menu on a local storefront the styles section always appears at the top style variations are defined in the config json file the order they appear in within the config file determines the display order in the rendered theme editor below that we have a number of expandable sub sections each sub section and setting within the sub section is defined in schema Json.
The sub section and setting names are arbitrary and the order they appear in within schema design determines their order here five data types are supported by the theme editor color font select check box and image dimension first let’s look at color you may recall in a previous post that I created a key value pair in config.json to change the color of the theme credit information in the footer here is the key value pair and if I swap to the footer S CSS file I could see the custom saft function here which reads this key name then pulls in the hex color value specified in config json returning this hot pink color which we see in the footer.
Since I’ve created a key for this in config.json I can now add it as an editable option within the theme editor in schema json I’ll scroll to the bottom of the file well there is already a section for footer settings the name label is what creates this order section in the theme editor UI.
I’ll add a new color object to this section for my footer credit text color for type I’ll use color this will render a box for users to type hex values into as well as a color picker the label is what we want the display name to be I’ll use theme credit text color the ID must match the key name existing in config.json in this case color – powered by now I’ll pull the local store back up and we can see the new setting in the footer section within sections headings can be added to create subcategories which can make a section easier to navigate.
I’ll add some headings to the footer section to separate the color options from the toggle options slopping back to schema dodging I’ll add two new objects to create headings the first I’ll add right above my two color options we’re going to use a type statement like we did when creating the color option but this won’t reference one of the five data types that the theme editor supports instead I want to use heading as the value this declares a display caption in the theme editor UI then I want to add a line for content this is where I add the display text for this heading I’ll use colors.
Now I’ll do the same thing right above the to toggle options the type will again be heading and I’ll set the content to toggles refreshing the local storefront the footer section is now showing me subcategory headings next we’ll look at the font data type in a previous post I added a few fonts to my theme a couple of Google fonts and one custom font that was added in the assets fonts directory I can use these songs in schema dodgey seems to provide font choices in that the editor and even add Google font options that were not listed as default in config.json.
Here for example are the font selection options for headings within the store you’ll see here the data type is font the label is font family that’s the display name that appears over the rendered drop-down list in the theme editor UI the ID is the key name that appears within config.json in this case is headings – font the options section is where you define which font options are selectable each font option listed has a group label and value the group designation is not necessary and you can omit it.
However the group provides a subheading in the drop down menu that allows you to categorize similar fonts together for example open sans bold open sans light and open sans regular italic could all be added as options and they could share the group heading open sans the label is the name of the font as it will appear in the drop-down list the value is the font family name as with setting a font in the config.json file calling in a Google font here you should name it Google underscore and then the name of your selected Google font in a previous post.
I’d set Chui as the font to use for my headings under the existing font options I’ll add the following I’ll add another Google font one that’s not referenced in config json below my entry for Chewie I’ll add a new option for the font named lobster again on the value I’ll use Google underscore at the beginning and then lobster the name of this particular Google font after refreshing the store.
I can see the new font options for my headings and I could swap between Shoei and lobster and the other fonts that were also added to the theme by default the custom non Google font that I added to the theme for my logo can also be made an option in the theme editor here in the logo section.
I’ll add a new option for fancy font it will look much the same as when I added the Google font options but the value area will not have the Google underscore at the beginning of the font name value when adding an on Google font though there is an extra step you need to take if we scroll up a little we can see where the data type label ID and options are designated for this logo font selection in this section.
We’ll also need to add the following if we swap back to the local store and select the new fancy font there’s a refresh prompt within the theme editor preview if we click on this the font is correctly applied when using an on Google font you must specify this force reload or else the preview will not properly update similar to the font type select types generate a drop-down list these select types can be used for a wide variety of theme customizations for example the font size options that appear in the typography section are created with the Select data type.
I’m going to create a new option to change my button shapes the defaults I see when looking at the carousel call-to-action is a squared looking button I want to add more rounded and leaf shaped options I’ll start by creating a key in config.json under the main settings area we’ve got a section defining button colors I’ll add my new key in this area just to keep like settings together I’ll name the key button – shape and assignment an arbitrary value of square.
Next I’ll create my select option in schema dodging within the theme editor there’s already a section devoted to buttons so we’ll add the new option at the top of this list I’ll create a new section with the data type select my label will be button shape and the ID will be button – shape to match what I created in config.json then the last section options is where I define my values that show up in the drop-down for the first one my label will be squared and the value.
I’ll also set to square this is the default for how buttons are already styled the next I’ll label round it and put rounded as the value and the last will be a label of leaf with a value of leaf next I need to define in my CSS what these values actually mean for my buttons the file that controls the button styling in cornerstone is assets FCSS components foundation buttons buttons F CSS so I’ll get that file opened up at the top of this file I’ll add the following this creates a mapping where the button shape variable will pull in as a text string whatever value is currently set for the button – shape key.
Next I’ll add my additional styling under the button element I’ll use an if directive against the button shape variable mapping above to adjust the styling based on the selection from the theme editor if the button shape variable pulls in the string rounded it’ll add this border radius of 25 pixels the button shape variable pulls in the leaf string then the border-radius will apply this 15 and 50 pixel styling to give us the leaf shape.
Now let’s swap to the storefront and check out the new button shape option swapping between my selections I can see the button shape changing in the preview next we’ll add a check box type this enables toggling of the boolean property or an on/off button in my local storefront I can see that both category pages and web content pages show up in my top navigation some merchants may not want the content pages to show up in the nav.
So I’ll create a toggle to turn that part of the menu on and off first I’ll create a key in config.json I’ll make it in this section here were the toggles for credit card logos and quick view with I’ll give this key the name show pages menu and set the value to true so that by default the menu will show up in the navigation.
Now I’ll create the checkbox option in schema json within the theme editor there’s a section for header settings so added at the top of this section my type will be checkbox the label will be show page menu in header and then the ID will be show pages menu for the key that was created in config.json we don’t need to create any options or values as this checkbox type will populate a checkbox in the storefront which will pass back a true or false value depending on whether it is checked or unchecked now I need to tie this true/false toggle to the page menu.
I’m going to open up components common navigation menu HTML here toward the top we can see where it creates a list item in the navigation for each top-level category right under that it creates alist item for each top of Paige I’m going to add an if helper around this webpage section let’s look at the local store and test the new toggle now if the show pages menu toggle returns true it will render the page section of the menu if it returns false it will not render the web page menu leaving just the categories in the top navigation the last type.
We’ll look at is the image dimension data type this lets a user specify dimensions for images used around the store like product images or the stores logo the config.json default value for an image dimension type is a string it can be either original or a horizontal by vertical dimensions in the format number X number in this example we’ll add the option for users to specify the size of swatches that show up on a product page many merchantst use swatches to show images of a font for engraving or other uses where it’s small twenty by twenty image just doesn’t work.
We’ll start by creating a key in config.json I’ll add the key here for swatch underscore size in the area where the other image dimension keys are and give it the current theme default value of 22 X 22 now I’ll create the image dimension options in schema dodging there is a section here for product configuration which already has image dimension types to resize product images.
I’ll go ahead and add my new option for swatches in this section for my data type on this one I’ll use image dimension the label will be swatch size and the ID is swatch underscore size to match the key I created in config json this is another theme editor option to which I need to add or three Loeb.
Finally we’ll add our options the options will have the first label as standard with a value of 22 X 22 which is what the theme has as a default the second option will have a label of specified dimensions with a value of custom this custom value will render text input fields for a user to specify their pixel dimensions if we swap over to the local store we can now see the edit option within the theme editor but it doesn’t do anything yet we now need to get the custom inputs to change the swatch sizes.
There are two types of swatches that can be used on a store a color box generated using a color picker or a user can also upload an image we’ll start with the uploaded image and the components products options directory is this file swatch HTML you’ll see two classes here for the swatches forum – options – variant – color and form – options – variant – pattern the pattern one is the uploaded image type.
We can see that the get image helper is being used and the image it pulls in is being sized by thumb underscore size here we need to swap out thumb underscore size with swatch underscore size we swap to the local store and try to adjust the dimensions on the swatch we can see that it doesn’t actually update yet in one of the SPSS files the swatch size is being limited by this square mixin.
We’ll need to override this to get our custom dimensions working I’ll create a new partial pfaff file to keep this separate and easy to find under assets at CSS layouts products I’ll add a new file underscore products watch CSS remember image dimension comes in as a string with the format number X number so we need to convert this string somehow and pull out those width and height values.
I’ll start by creating an arbitrarily named variable value of swatch size then I’ll use the custom SAS function stencil string to pull in the swatch underscore size value specified in the theme editor now we’ll need to use some string functions to split this string up into usable parts to style things correctly the constant in any image dimension string will be the X separating the width from the height.
I’ll create a variable position of X and use the string function string index which will allow me to find the first occurrence of a substring we’ll be using the variable value of swatch size as the string we’re searching and X as the value of the substring we want to find now that we have a variable that can find where the X is for a given value of swap size we can use the string slice function to extract the width and height of sub strings.
I’ll make a variable for width and extract everything from the start of our value of swatch size string with the starting position of 0 to the last character before the X in the string position of X minus 1 I’ll then make a height variable and extract everything after the X from the value of swatch size string so position of X plus 1 I don’t need to specify an end point for this as it will automatically go to the last character of the string.
If it is an otherwise specified now we can assign these substring values as a width and height for our swatch boxes we want to make sure to include both swatch classes for color and pattern this will take care of resizing the color picker box as well as resizing the box was constraining the uploaded image swatch the last thing we’ll want to do is import this new partial so we’ll go up a level in our F CSS directory to the underscore layouts s CSS file will add at import products slash products watch to pull in our new CSS.
Now if we visit the local storefront and change our swatch dimensions it works to recap we covered accessing the local version of your team’s theme editor we also covered the available data types to use when creating customization options within the theme editor as always you can find documentation on this and other features at stencil.bigCommerce.com/docs in the next post we’ll cover using the Edit theme files feature to access and edit theme code from within the stores control panel or contact us now if you need help with theme editor customization.