Theme fields.json file

Develop, Build & Integrate CMS Development
3

Hey @tmcmillan99,

as @Jnix284 mentioned - the theme fields.json is for global settings and to keep consitency.
There are unlimited possibilities and while the boilerplate has “only” settings for colors, fonts, buttons and a few other global elements, you can be very creative and control almost every aspect of your theme and make module style-fields almost obsolete. You don’t need to stick to the grouping of the boilerplate. It’s completly up to you. This is great if you don’t want to provide a lot of flexibility to the users and focus on brand consistency. The only thing to keep in mind is - if you’ve started with the boilerplate and want to change the gouping, you’ll need to modify the existing variables too.

The theme I’ve written for my company(GraphiSpot) is extremly large but provides me(as a user) only the options I need in the modules.

For instance: I’m setting the colors in the color settings via the brand-kit but can override them via a color picker but the modules don’t have a color picker for colors but instead I’m using a choice/select option to choose between primary,light, dark colors that are applied - most times - via CSS classes.

To achieve this I’ve created a for-loop that runs through all color fields and generates a bg-COLOR and text-COLOR class.

I’m also controlling every aspect of every module via the theme fields.json. So If I want to display a author image in my blog card(blog is currently not published), it’s a simple boolean inside the theme setting. Should the author name be displayed as FIRSTNAME LASTNAME, or just FIRSTNAME - a choice option that is written in the blog card macro like

{% if theme.blog.blog_cards.author_name == "firstname"%}
 {%- set author_name = content.blog_post_author.display_name|split(" ")|first -%}
{%- else -%}
 {%- set author_name = content.blog_post_author.display_name -%}
{%- endif -%}

<span class="author-name">{{author_name}}</span>

Is it easy to write?

Not really.

Do I recommend this?

Only if you have a lot of time and get paid enough since you’ll most likely invest more time in planning than writing acutal code. :grinning_face:

My theme fields.json is around 6000 lines of code long and I’m far from done (I think it will be around 10-12k lines ones it’s done)

The current grouping of my fields.json is build like this

  • colors
    • primary
    • secondary
      • common
        • light
        • dark
        • white
        • black
      • system
        • success
        • error
        • info
        • warning
  • fonts
    • base font size
    • line height
    • desktop sizes
      • h1-h6
    • tablet sizes
      • h1-h6
    • mobile sizes
      • h1-h6
    • link styles
      • default
      • hover
      • focus
  • buttons
    • big
    • default
    • small
    • transition time
    • primary button
      • default
        • background color
        • padding
        • text color
        • add shadow
        • shadow settings
          • x
          • y
          • blur
          • spread
          • color
      • hover
        • same options as default
      • focus
        • same options as default
      • disabled
        • same options as default
    • secondary button
      • same options as primary
  • header
    • background color
    • fixed header
    • dynamic header
    • dynamic header settings
      • height
      • transition time
      • padding
      • background color
    • main nav
      • color
      • dropdowns
        • dropdown background
        • padding
        • border radius
  • … and A LOT more options for every module and almost every aspect of the theme

As of inherited properties in a module - if you’re talking about inherit theme fields.json properties into modules… Totally possible. You even have several ways to do so.

  1. Simply write the theme fields path into the module.
    Example: You have a number field which you’re using as a border-radius for card modules. This field is located in theme/modules/cards/border-radius - the corresponding code would look like this
<div class="card" style="{{ theme.modules.cards.border_radius ~px }}">
something
</div>

Do I recommend it? not really since you might end up in an endless tunnel of searching for all variables through out all modules/instances if the client or somebody would request a change.

  1. Creating a helper file that has a bunch of CSS classes.
    Example: Let’s stick with the border-radius but this time you have a big, default and small border-radius. You can create a seperate CSS file with something like this
.br-big{
 -webkit-border-radius: {{theme.modules.cards.big_radius ~ px}};
 -moz-border-radius: {{theme.modules.cards.big_radius ~ px}};
 -o-border-radius: {{theme.modules.cards.big_radius ~ px}};
 border-radius: {{theme.modules.cards.big_radius ~ px}};
}

.br-default{
 -webkit-border-radius: {{theme.modules.cards.default_radius ~ px}};
 -moz-border-radius: {{theme.modules.cards.default_radius ~ px}};
 -o-border-radius: {{theme.modules.cards.default_radius ~ px}};
 border-radius: {{theme.modules.cards.default_radius ~ px}};
}

.br-small{
 -webkit-border-radius: {{theme.modules.cards.small_radius ~ px}};
 -moz-border-radius: {{theme.modules.cards.small_radius ~ px}};
 -o-border-radius: {{theme.modules.cards.small_radius ~ px}};
 border-radius: {{theme.modules.cards.small_radius ~ px}};
}

and have a style choice field(“br_radius”) with “big”, “default” and “small” as values.

The module code would look like this

<div class="card br-{{module.styles.br_radius}}">
something
</div>

Do I recommend this? Kinda, yes. This gives you the ability to quickly change something globally in the future.

Additionally I would recommend you to create a seperate variables file somewhere in your theme where you store only the variables. This file is getting included via a single line of code into all of your css and other files.

Such file could look something like this:

{% set big_border_radius = theme.modules.cards.big_radius ~ px %}
{% set default_border_radius = theme.modules.cards.default_radius ~ px %}
{% set small_border_radius = theme.modules.cards.small_radius ~ px %}

the helper file would look like this

{%- include "./_variables.css" -%}

.br-big{
 -webkit-border-radius: {{ big_border_radius }};
 -moz-border-radius: {{ big_border_radius }};
 -o-border-radius: {{ big_border_radius }};
 border-radius: {{ big_border_radius }};
}

.br-default{
 -webkit-border-radius: {{ default_border_radius }};
 -moz-border-radius: {{ default_border_radius }};
 -o-border-radius: {{ default_border_radius }};
 border-radius: {{ default_border_radius }};
}

.br-small{
 -webkit-border-radius: {{ small_border_radius }};
 -moz-border-radius: {{ small_border_radius }};
 -o-border-radius: {{ small_border_radius }};
 border-radius: {{ small_border_radius }};
}

This allows you to modify things even quicker and more globally in the future since you have to modify only one file: the variables file

And as for “something like the Design manager for creating theme fields.json files” - you’re right, there is no official(!) thing for this. But the amazing BJ Szyjakowski has created this free mac app which allows you to load and edit fields.json files or create new ones.

best, Anton