Defining Global Styles

You can manage your custom theme’s front-end components by configuring the config.json file. This file is made up of different keys and values that define the global styles shoppers will see on a theme. This config.json file’s functions are to:

  • Provide global context for Stencil’s CSS and Handlebars resources.
  • Provide values for the Store Design GUI to manage.
  • Provide metadata for your theme’s listing in the Theme Marketplace.
  • Define variations included in your custom theme

Keys and Example Values

For a list of all available keys and values in config.json, see Theme Objects in the API Reference.

Requirements and Restrictions

The config.json file must meet the following requirements:

  • It must be named config.json, must reside in the root of your <theme-name> top level subdirectory (e.g.: /cornerstone/config.json), and must contain valid JSON.
  • The maximum allowable size for a theme’s config.json file is 64 KB. Exceeding this limit will trigger an error upon uploading the theme to BigCommerce.
  • Each key’s value is restricted to 64 characters. Exceeding this limit will similarly trigger an upload error.
  • Other than these size constraints, there is no limit on the number of keys and values that you can place in a theme’s config.json.

Carefully check your theme against all the listed requirements – including the required keys within the meta object and variations array. While some requirements are not enforced in local development, they will be validated when you later upload your theme to BigCommerce.

Required Themewide Keys

The config.json file must contain at least the following keys, with appropriate values (as outlined above):

  • name
  • version
  • settings (must be a valid JSON object)
  • variations (an array of at least one, and at most four, variation objects)
  • meta (an object; see specific requirements below)

Required meta Keys

The meta object must contain at least the following keys, with appropriate values:

  • price
  • author_name
  • author_email
  • author_support_url
  • documentation_url

For illustration, below is a commented excerpt:

Required Meta Keys and Values
{
  ...
  "meta": {
    "price": 15000, // in cents; non-negative integer, minimum 0
    "author_name": "eCommerce Themes, Inc.", // Must be a string, not null
    "author_email": "support@example.com", // Must be a string, should be a valid email address, not null
    "author_support_url": "http://example.com/contactus", //  Must be a string, should be a valid URL, not null
    "documentation_url": "http://example.com/guide", // Must be a string, limit of 255 characters, not null
    "composed_image": "path/to/composed.png", // Must be a string path to the composed-image file
    "features": [ // Array of feature strings, all of which must be in the list enumerated here:
          https://github.com/bigcommerce/theme-registry/blob/master/app/schemas/theme_config.json#L33
      "fully_responsive" // Must include at least one feature, and no duplicate entries
    ]
  },
  ...
}

Required variation Keys

At least one variation is required in a theme. For each variation that you choose to include in your theme, you must provide at least the following keys and sub-element, with appropriate values:

  • name
  • id
  • meta
  • description

For illustration, below is a code sample from Cornerstone:

Required Variation Object with Key/Value pairs
"variations": [
    {
      "name": "Light",
      "id": "light",
      "meta": {
        "desktop_screenshot": "desktop_light.png",
        "mobile_screenshot": "mobile_light.png",
        "description": "Ideal for a wide range of businesses and brands, this design is fully responsive, simple, and ready for you to add your branding, logo, and products. ...",
    ...
    }
  ]

New Products Example

To customize your theme’s appearance at a global level, the values that you define in the {theme-name}/config.json file interact with local resources. Your config.json definitions set global defaults for templates, front-matter attributes, and Handlebars resources throughout your theme. You can also define custom variables in config.json, named according to your needs.

To see how interactions with config.json values work, first note the default values in config.json for the homepage_new_products_count and product_list_display_mode keys:

{
"settings": {
  "homepage_new_products_count": 12,
  "product_list_display_mode": "grid",
  }
}

Next, open your {theme-name}templates/pages/home.html file. Highlighted in bold below is a statement that uses the theme-wide settings above to customize an API request to the server.

(Note the reference to the homepage_new_products_count key in the file’s front matter, between the two “” delimiters. If your current theme’s home.html front matter omits this products:new:limit definition, paste it in for this demonstration.)

products:
  new:
    limit: {{theme_settings.homepage_new_products_count}}
  featured:
    limit: {{theme_settings.homepage_featured_products_count}}
  top_sellers:
    limit: {{theme_settings.homepage_top_products_count}}
carousel: {{theme_settings.homepage_show_carousel}}
blog:
    recent_posts:
        limit: {{theme_settings.homepage_blog_posts_count}}

{{#partial "hero"}}

<!-- [...] -->

{{/partial}}
{{> layout/base}}

If you load your storefront’s home page (by default, http://localhost:3000, you should see a “New Products” section that displays 12 products in a grid.

Changing Page Layout Using Local Front Matter

In the {theme-name}templates/pages/home.html front matter, products > featured is listed. This controls how many products appear on the home page. This is set by the config.json theme_settings.homepage_featured_products_count}. This example shows how you can set theme wide configurations in the front matter using the config.json.


<!-- [...] -->
products:
  featured:
      limit: {{theme_settings.homepage_featured_products_count}}
<!-- [...] -->

Next, try changing the limit: {{theme_settings.homepage_featured_products_count}} statement in the home.html file to a hard-coded limit: 2, as indicated below in bold:


products:
  <!-- [...] -->
  featured:
      limit: 2
  <!-- [...] -->

<!-- [...] -->

{{#partial "page"}}

<!-- [...] -->

<div class="main full">
  {{#if products.featured}}
      {{> components/products/featured products=products.featured columns=2}}
  {{/if}}
</div>
{{/partial}}
{{> layout/base}}

If you now reload your storefront’s home page in your browser, you should see the number of displayed “Featured Products” change from its default number (as specified in config.json) to two.

Retrieving Specific config.json Values through Sass

In config.json, global variables bring dynamic values into the framework. Sass imports these global variables’ values to gracefully handle data like theme-wide colors’ hexadecimal values, and to make the data available to Store Design. Here is one short snippet from config.json:

{
<!-- [...] -->
"color-highlight": "#00abc9",
"color-highlightDark": "#f2f2f2",
"color-highlightDarker": "#dfdfdf",
<!-- [...] -->
}

Here are the corresponding references in the default Stencil theme’s {theme-name}/assets/scss/settings/global/color/_color.scss file:

// ...
$color-highlight:       stencilColor("color-highlight");
$color-highlightDarker: stencilColor("color-highlightDarker");
$color-highlightDark:   stencilColor("color-highlightDark");
// ...

In config.json, try redefining one or more color variables to hex values of your choice. Then re-render your theme’s home page to see the effects.

Adding/Removing Components

The storefront properties that Stencil abstracts as Handlebars resources are completely portable between HTML files. For an example of how this works, first open any storefront page in a browser. In the page’s footer, note the appearance of Categories.

Next, open your {theme-name}/templates/components/common/footer.html file in a text editor. As indicated below, cut (or copy and comment out) the code section shown below.

footer.html
<footer class="footer" role="contentinfo">
  <div class="container">
      <section class="footer-info">
          <!-- [...] -->
<article class="footer-info-col footer-info-col--small">
  <h5 class="footer-info-heading">{{lang 'footer.categories'}}</h5>
  <ul class="footer-info-list">
      {{#each categories}}
      <li>
          <a href="{{url}}">{{name}}</a>
      </li>
      {{/each}}
  </ul>
</article>

If you now refresh the storefront page in your browser, the Categories list should disappear from the footer.

Next, create a new {theme-name}/templates/components/footer/ subdirectory. Paste the code block from the previous cut/copy into a new file named {theme-name}/templates/components/footer/categories.html, and save it:

categories.html
<article class="footer-info-col footer-info-col--small">
  <h5 class="footer-info-heading">{{lang 'footer.categories'}}</h5>
  <ul class="footer-info-list">
      {{#each categories}}
      <li>
          <a href="{{url}}">{{name}}</a>
      </li>
      {{/each}}
  </ul>
</article>

Next, back in /templates/components/common/footer.html, add a reference to your new path/file, as indicated below in comments:

footer.html
<footer class="footer" role="contentinfo">
  <div class="container">
      <section class="footer-info">
          <!-- [...] -->
          {{> components/footer/categories}}
          <!-- [...] -->
      </section>
  </div>
</footer>

If you now refresh storefront pages in your browser, the Categories list should reappear in the footer. The component returns even though you have moved its data resources to an arbitrary new location, and referenced them indirectly.

Resources

Additional Resources