{"_id":"58112e73ded0340f0085d070","category":{"_id":"58112e72ded0340f0085d02c","project":"551e85be610f400d00837db7","__v":0,"version":"58112e71ded0340f0085d02a","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-07T18:58:09.521Z","from_sync":false,"order":2,"slug":"theme-logic","title":"Theme Logic & Components"},"__v":0,"parentDoc":null,"project":"551e85be610f400d00837db7","user":"56439928549c4d0d00d7e910","version":{"_id":"58112e71ded0340f0085d02a","project":"551e85be610f400d00837db7","__v":4,"createdAt":"2016-10-26T22:30:09.862Z","releaseDate":"2016-10-26T22:30:09.862Z","categories":["58112e72ded0340f0085d02b","58112e72ded0340f0085d02c","58112e72ded0340f0085d02d","58112e72ded0340f0085d02e","58112e72ded0340f0085d02f","58112e72ded0340f0085d030","58112e72ded0340f0085d031","58112e72ded0340f0085d032","58112e72ded0340f0085d033","58112e72ded0340f0085d034","581137cc604d3c230048b7e4","58dc367221742d0f00a73f98","590768e54669da0f00db5c0b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"new designer","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-30T15:08:43.526Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Heads up!\",\n  \"body\": \"Theme settings are only used by the new designer launched in June 2016. Not sure which designer you're using? [Check here](https://help.cratejoy.com/hc/en-us/articles/211679366-Do-I-have-the-new-designer-or-the-old-designer-).\"\n}\n[/block]\nThe Cratejoy Designer customizes all site content and styles via simple, configurable strings that we call \"settings\". These string settings can be accessed in any HTML or CSS file and can be reused across your theme.\n\nYou can add, remove, or change these settings to add more functionality to your theme inside the Cratejoy Designer.\n\n# Defining Settings\n\nEach component has a `settings_schema.json` file that defines the different settings options available, their input type, and how they should be grouped in the UI.\n\n## Setting Schema\n\n### Groups\n\n`settings_schema.json` is a JSON array made up of setting groups for organization. Each group has the following properties:\n\n| Property   | Type    | Notes                                                                                                 |\n|------------|---------|-------------------------------------------------------------------------------------------------------|\n| `label`    | string  | The label shown at the top of the expandable group in the designer                                    |\n| `global`   | boolean | Specifies whether or not the group should be shown in the \"Global Styles\" tab or the main content tab |\n| `settings` | array   | An array of settings definitions in the form outlined below                                           |\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"label\\\": \\\"My Group\\\",\\n    \\\"settings\\\": [\\n      { ... }\\n    ]\\n  }\\n]\",\n      \"language\": \"json\",\n      \"name\": \"settings_schema.json\"\n    }\n  ]\n}\n[/block]\n### Settings\n\nEach setting has the following properties:\n\n| Property   | Type    | Notes                                                                                                                        |\n|------------|---------|------------------------------------------------------------------------------------------------------------------------------|\n| `id`       | string  | Key for accessing the setting's value inside templates and as the storage key in `settings_data.json`                        |\n| `label`    | string  | Label for the setting's input inside the designer side panel.                                                                |\n| `type`     | string  | The type of input that should be presented in the designer side panel.                                                       |\n| `inherits` | string  | The `id` of another setting to default to                                                                                    |\n| `boolean`  | boolean | Specifies that the setting is used to show or hide content in the theme. Should be true if ever used inside an if/else block |\n\n#### Setting Types\n\nEach setting has a specified type that indicates which UI the user sees.\n\n| Type        |                                                                  |\n|-------------|------------------------------------------------------------------|\n| `text`      | A single line text input                                         |\n| `richtext`  | A rich text editor that outputs HTML                             |\n| `image`     | An image upload, includes a basic image editor and cropping tool |\n| `color`     | A color picker                                                   |\n| `font_face` | A font face dropdown, shows top 200 fonts from Google Fonts      |\n| `font_size` | A font size picker                                               |\n| `link`      | A single line text input that validates to be a valid URL        |\n| `switch`    | A boolean on/off switch                                          |\n| `divider`   | A simple horizontal divider in the settings list                 |\n\n#### Related Setting Groups\n\nSome settings are related to a single element on the page, such as the styles for text or a button. Using special naming conventions will group these settings into a single sub-group within your top level setting group.\n\nThe label used for the group is always pulled from the `font_face` setting.\n\n##### Font Groups\n\nFont groups can include a `font_face`, `font_size`, and `color` settings, combined into a single group. The convention for this grouping are:\n\n- `<your_name>/font_face`\n- `<your_name>/font_size`\n- `<your_name>/color`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"label\\\": \\\"Fonts\\\",\\n    \\\"global\\\": true,\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"page_heading/font_face\\\",\\n        \\\"label\\\": \\\"Heading 1\\\",\\n        \\\"type\\\": \\\"font_face\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"page_heading/color\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"page_heading/font_size\\\",\\n        \\\"type\\\": \\\"font_size\\\"\\n      }\\n    ]\\n  }\\n]\",\n      \"language\": \"json\",\n      \"name\": \"settings_schema.json\"\n    }\n  ]\n}\n[/block]\n##### Button Groups\n\nButton groups can include a `font_face`, `font_size`, and 4 different `color` settings, combined into a single group. The convention for this grouping are:\n\n- `<your_name>button/font_face`\n- `<your_name>button/font_size`\n- `<your_name>button/color`\n- `<your_name>button/text_color`\n- `<your_name>button/hover_color`\n- `<your_name>button/hover_text_color`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"label\\\": \\\"Buttons\\\",\\n    \\\"global\\\": true,\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"primary_button/font_face\\\",\\n        \\\"label\\\": \\\"Primary Button\\\",\\n        \\\"type\\\": \\\"font_face\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/font_size\\\",\\n        \\\"type\\\": \\\"font_size\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/color\\\",\\n        \\\"type\\\": \\\"color\\\",\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/text_color\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/hover_color\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/hover_text_color\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      }\\n    ]\\n  }\\n]\",\n      \"language\": \"json\",\n      \"name\": \"settings_schema.json\"\n    }\n  ]\n}\n[/block]\n#### Inheritance\n\nSettings can inherit their values from other settings. For example, a theme can define a color palette that other settings can use while still allowing specific settings to be overridden. This makes styling a theme much quicker without loosing fine-grained customizability.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"label\\\": \\\"Color Scheme\\\",\\n    \\\"global\\\": true,\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"primary_color\\\",\\n        \\\"label\\\": \\\"Primary\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"secondary_color\\\",\\n        \\\"label\\\": \\\"Secondary\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      }\\n    ]\\n  },\\n  {\\n    \\\"label\\\": \\\"Navigation\\\",\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"logo_color\\\",\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"label\\\": \\\"Logo Color\\\",\\n        \\\"inherits\\\": \\\"primary_color\\\"\\n      }\\n    ]\\n  }\\n]\",\n      \"language\": \"json\",\n      \"name\": \"settings_schema.json\"\n    }\n  ]\n}\n[/block]\n# Full Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"label\\\": \\\"Color Scheme\\\",\\n    \\\"global\\\": true,\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"primary_color\\\",\\n        \\\"label\\\": \\\"Primary\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"secondary_color\\\",\\n        \\\"label\\\": \\\"Secondary\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      }\\n    ]\\n  },\\n  {\\n    \\\"label\\\": \\\"Fonts\\\",\\n    \\\"global\\\": true,\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"page_heading/font_face\\\",\\n        \\\"label\\\": \\\"Heading 1\\\",\\n        \\\"type\\\": \\\"font_face\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"page_heading/color\\\",\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"inherits\\\": \\\"secondary_color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"page_heading/font_size\\\",\\n        \\\"type\\\": \\\"font_size\\\"\\n      }\\n    ]\\n  },\\n  {\\n    \\\"label\\\": \\\"Buttons\\\",\\n    \\\"global\\\": true,\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"primary_button/font_face\\\",\\n        \\\"label\\\": \\\"Primary Button\\\",\\n        \\\"type\\\": \\\"font_face\\\",\\n        \\\"inherits\\\": \\\"page_body/font_face\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/font_size\\\",\\n        \\\"type\\\": \\\"font_size\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/color\\\",\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"inherits\\\": \\\"primary_color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/text_color\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/hover_color\\\",\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"inherits\\\": \\\"secondary_color\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"primary_button/hover_text_color\\\",\\n        \\\"type\\\": \\\"color\\\"\\n      }\\n    ]\\n  },\\n  {\\n    \\\"label\\\": \\\"Hero\\\",\\n    \\\"settings\\\": [\\n      {\\n        \\\"id\\\": \\\"hp_hero_image\\\",\\n        \\\"label\\\": \\\"Image\\\",\\n        \\\"type\\\": \\\"image\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"divider\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"hp_hero_block_color\\\",\\n        \\\"label\\\": \\\"Background\\\",\\n        \\\"type\\\": \\\"color\\\",\\n        \\\"inherits\\\": \\\"secondary_color\\\"\\n      },\\n      {\\n        \\\"type\\\": \\\"divider\\\"\\n      },\\n      {\\n        \\\"id\\\": \\\"hp_hero_content\\\",\\n        \\\"type\\\": \\\"richtext\\\"\\n      }\\n    ]\\n  }\\n]\",\n      \"language\": \"json\",\n      \"name\": \"settings_schema.json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"settings-details","type":"basic","title":"Settings in Depth"}
[block:callout] { "type": "info", "title": "Heads up!", "body": "Theme settings are only used by the new designer launched in June 2016. Not sure which designer you're using? [Check here](https://help.cratejoy.com/hc/en-us/articles/211679366-Do-I-have-the-new-designer-or-the-old-designer-)." } [/block] The Cratejoy Designer customizes all site content and styles via simple, configurable strings that we call "settings". These string settings can be accessed in any HTML or CSS file and can be reused across your theme. You can add, remove, or change these settings to add more functionality to your theme inside the Cratejoy Designer. # Defining Settings Each component has a `settings_schema.json` file that defines the different settings options available, their input type, and how they should be grouped in the UI. ## Setting Schema ### Groups `settings_schema.json` is a JSON array made up of setting groups for organization. Each group has the following properties: | Property | Type | Notes | |------------|---------|-------------------------------------------------------------------------------------------------------| | `label` | string | The label shown at the top of the expandable group in the designer | | `global` | boolean | Specifies whether or not the group should be shown in the "Global Styles" tab or the main content tab | | `settings` | array | An array of settings definitions in the form outlined below | [block:code] { "codes": [ { "code": "[\n {\n \"label\": \"My Group\",\n \"settings\": [\n { ... }\n ]\n }\n]", "language": "json", "name": "settings_schema.json" } ] } [/block] ### Settings Each setting has the following properties: | Property | Type | Notes | |------------|---------|------------------------------------------------------------------------------------------------------------------------------| | `id` | string | Key for accessing the setting's value inside templates and as the storage key in `settings_data.json` | | `label` | string | Label for the setting's input inside the designer side panel. | | `type` | string | The type of input that should be presented in the designer side panel. | | `inherits` | string | The `id` of another setting to default to | | `boolean` | boolean | Specifies that the setting is used to show or hide content in the theme. Should be true if ever used inside an if/else block | #### Setting Types Each setting has a specified type that indicates which UI the user sees. | Type | | |-------------|------------------------------------------------------------------| | `text` | A single line text input | | `richtext` | A rich text editor that outputs HTML | | `image` | An image upload, includes a basic image editor and cropping tool | | `color` | A color picker | | `font_face` | A font face dropdown, shows top 200 fonts from Google Fonts | | `font_size` | A font size picker | | `link` | A single line text input that validates to be a valid URL | | `switch` | A boolean on/off switch | | `divider` | A simple horizontal divider in the settings list | #### Related Setting Groups Some settings are related to a single element on the page, such as the styles for text or a button. Using special naming conventions will group these settings into a single sub-group within your top level setting group. The label used for the group is always pulled from the `font_face` setting. ##### Font Groups Font groups can include a `font_face`, `font_size`, and `color` settings, combined into a single group. The convention for this grouping are: - `<your_name>/font_face` - `<your_name>/font_size` - `<your_name>/color` [block:code] { "codes": [ { "code": "[\n {\n \"label\": \"Fonts\",\n \"global\": true,\n \"settings\": [\n {\n \"id\": \"page_heading/font_face\",\n \"label\": \"Heading 1\",\n \"type\": \"font_face\"\n },\n {\n \"id\": \"page_heading/color\",\n \"type\": \"color\"\n },\n {\n \"id\": \"page_heading/font_size\",\n \"type\": \"font_size\"\n }\n ]\n }\n]", "language": "json", "name": "settings_schema.json" } ] } [/block] ##### Button Groups Button groups can include a `font_face`, `font_size`, and 4 different `color` settings, combined into a single group. The convention for this grouping are: - `<your_name>button/font_face` - `<your_name>button/font_size` - `<your_name>button/color` - `<your_name>button/text_color` - `<your_name>button/hover_color` - `<your_name>button/hover_text_color` [block:code] { "codes": [ { "code": "[\n {\n \"label\": \"Buttons\",\n \"global\": true,\n \"settings\": [\n {\n \"id\": \"primary_button/font_face\",\n \"label\": \"Primary Button\",\n \"type\": \"font_face\"\n },\n {\n \"id\": \"primary_button/font_size\",\n \"type\": \"font_size\"\n },\n {\n \"id\": \"primary_button/color\",\n \"type\": \"color\",\n },\n {\n \"id\": \"primary_button/text_color\",\n \"type\": \"color\"\n },\n {\n \"id\": \"primary_button/hover_color\",\n \"type\": \"color\"\n },\n {\n \"id\": \"primary_button/hover_text_color\",\n \"type\": \"color\"\n }\n ]\n }\n]", "language": "json", "name": "settings_schema.json" } ] } [/block] #### Inheritance Settings can inherit their values from other settings. For example, a theme can define a color palette that other settings can use while still allowing specific settings to be overridden. This makes styling a theme much quicker without loosing fine-grained customizability. [block:code] { "codes": [ { "code": "[\n {\n \"label\": \"Color Scheme\",\n \"global\": true,\n \"settings\": [\n {\n \"id\": \"primary_color\",\n \"label\": \"Primary\",\n \"type\": \"color\"\n },\n {\n \"id\": \"secondary_color\",\n \"label\": \"Secondary\",\n \"type\": \"color\"\n }\n ]\n },\n {\n \"label\": \"Navigation\",\n \"settings\": [\n {\n \"id\": \"logo_color\",\n \"type\": \"color\",\n \"label\": \"Logo Color\",\n \"inherits\": \"primary_color\"\n }\n ]\n }\n]", "language": "json", "name": "settings_schema.json" } ] } [/block] # Full Example [block:code] { "codes": [ { "code": "[\n {\n \"label\": \"Color Scheme\",\n \"global\": true,\n \"settings\": [\n {\n \"id\": \"primary_color\",\n \"label\": \"Primary\",\n \"type\": \"color\"\n },\n {\n \"id\": \"secondary_color\",\n \"label\": \"Secondary\",\n \"type\": \"color\"\n }\n ]\n },\n {\n \"label\": \"Fonts\",\n \"global\": true,\n \"settings\": [\n {\n \"id\": \"page_heading/font_face\",\n \"label\": \"Heading 1\",\n \"type\": \"font_face\"\n },\n {\n \"id\": \"page_heading/color\",\n \"type\": \"color\",\n \"inherits\": \"secondary_color\"\n },\n {\n \"id\": \"page_heading/font_size\",\n \"type\": \"font_size\"\n }\n ]\n },\n {\n \"label\": \"Buttons\",\n \"global\": true,\n \"settings\": [\n {\n \"id\": \"primary_button/font_face\",\n \"label\": \"Primary Button\",\n \"type\": \"font_face\",\n \"inherits\": \"page_body/font_face\"\n },\n {\n \"id\": \"primary_button/font_size\",\n \"type\": \"font_size\"\n },\n {\n \"id\": \"primary_button/color\",\n \"type\": \"color\",\n \"inherits\": \"primary_color\"\n },\n {\n \"id\": \"primary_button/text_color\",\n \"type\": \"color\"\n },\n {\n \"id\": \"primary_button/hover_color\",\n \"type\": \"color\",\n \"inherits\": \"secondary_color\"\n },\n {\n \"id\": \"primary_button/hover_text_color\",\n \"type\": \"color\"\n }\n ]\n },\n {\n \"label\": \"Hero\",\n \"settings\": [\n {\n \"id\": \"hp_hero_image\",\n \"label\": \"Image\",\n \"type\": \"image\"\n },\n {\n \"type\": \"divider\"\n },\n {\n \"id\": \"hp_hero_block_color\",\n \"label\": \"Background\",\n \"type\": \"color\",\n \"inherits\": \"secondary_color\"\n },\n {\n \"type\": \"divider\"\n },\n {\n \"id\": \"hp_hero_content\",\n \"type\": \"richtext\"\n }\n ]\n }\n]", "language": "json", "name": "settings_schema.json" } ] } [/block]