From c7b1d20bff80912eb162638b9cc24138c9de7470 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 18 Nov 2024 07:03:17 -0800 Subject: [PATCH] Add appropriate lexers to code blocks Sentence-case headings Add MyST markup --- docs/customizing-volto-light-theme/theming.md | 99 +++++++++---------- 1 file changed, 48 insertions(+), 51 deletions(-) diff --git a/docs/customizing-volto-light-theme/theming.md b/docs/customizing-volto-light-theme/theming.md index 624cc80c..2a8de8fe 100644 --- a/docs/customizing-volto-light-theme/theming.md +++ b/docs/customizing-volto-light-theme/theming.md @@ -1,24 +1,22 @@ --- myst: html_meta: - "description": "Theming" - "property=og:description": "Theming" - "property=og:title": "Theming" - "keywords": "Plone, Volto, Training" + "description": "Extend the Volto Light Theme" + "property=og:description": "Extend the Volto Light Theme" + "property=og:title": "Extend the Volto Light Theme" + "keywords": "Plone, Volto, Training, Extend, Volto Light Theme" --- -# Extending VLT - -## Introduction +# Extend VLT In this section we'll extend the VLT to create a "dark" aesthetic for our project. The same patterns can be applied for other visual identity cases. -## **File Structure** +## File structure Let us start by setting up the recommended file structure. In your project add-on's {file}`src` folder, create a subfolder named {file}`theme`. Inside {file}`theme` create two empty files named {file}`_main.scss` and {file}`_variables.scss`. Refer to the following file system diagram: -``` +```console src/ ├── components ├── index.js @@ -27,11 +25,11 @@ src/ └── _variables.scss ``` -### **\_variables.scss** +### `_variables.scss` {file}`_variables.scss` is where you can override the base theme SCSS variables. -``` +```scss :root { --primary-color: black; --primary-foreground-color: lemonchiffon; @@ -46,48 +44,48 @@ src/ } ``` -### **\_main.scss** +### `_main.scss` {file}`_main.scss` is where you should put any custom styles. You can also include other SCSS or CSS files, as follows: -``` +```scss @import 'variables'; ``` -## **Block Themes** +## Block themes -Now, we need to change the available themes for the blocks by adding the following definition inside the `applyConfig` function in our project's `index.js`: +Now we need to change the available themes for the blocks by adding the following definition inside the `applyConfig` function in our project's {file}`index.js`: -``` - config.blocks.themes = [ - { - style: { - '--theme-color': 'black', - '--theme-high-contrast-color': 'darkslategrey', - '--theme-foreground-color': 'lemonchiffon', - '--theme-low-contrast-foreground-color': 'lightgrey', - }, - name: 'default', - label: 'Default', +```js +config.blocks.themes = [ + { + style: { + '--theme-color': 'black', + '--theme-high-contrast-color': 'darkslategrey', + '--theme-foreground-color': 'lemonchiffon', + '--theme-low-contrast-foreground-color': 'lightgrey', }, - { - style: { - '--theme-color': 'darkslategrey', - '--theme-high-contrast-color': 'black', - '--theme-foreground-color': 'lemonchiffon', - '--theme-low-contrast-foreground-color': 'lightgrey', - }, - name: 'green', - label: 'Green', + name: 'default', + label: 'Default', + }, + { + style: { + '--theme-color': 'darkslategrey', + '--theme-high-contrast-color': 'black', + '--theme-foreground-color': 'lemonchiffon', + '--theme-low-contrast-foreground-color': 'lightgrey', }, - ]; + name: 'green', + label: 'Green', + }, +]; ``` -## **Extending Addon Styles** +## Extend add-on styles -The theme provides the ability to extend or modify existing components. Let's create one more file named {file}`relatedItems.scss` to add specific styles for the addon, as follows: +The theme provides the ability to extend or modify existing components. Let's create one more file named {file}`relatedItems.scss` to add specific styles for the add-on, as follows: -``` +```console src/ ├── components ├── index.js @@ -100,7 +98,7 @@ src/ In the new {file}`_relatedItems.scss`, let's fix the text color, and add background color to the `.inner-container` element with the variables `--primary-foreground-color` and `--theme-high-contrast-color`. Lastly, let's use `--link-foreground-color` for the related items links: -``` +```scss .block.relatedItems { .inner-container { background: var(--theme-high-contrast-color); @@ -122,18 +120,19 @@ In the new {file}`_relatedItems.scss`, let's fix the text color, and add backgro And now we need to add {file}`_relatedItems.scss` in {file}`_main_.scss`: -``` +```scss @import 'blocks/relatedItems'; @import 'variables'; ``` -## **Enhancing a Block Schema** +## Enhancing a block schema -To be able to use the Block Width widget with our Related Items block we need to add it to the block schema; to do this we'll use a `schemaEnhancer`. A schema enhancer is a function that receives an object with `formData` (the block `data`), the `schema` (the original schema that we want to tweak), and the injected `intl` (to aid with internationalization). +To be able to use the Block Width widget with our Related Items block, we need to add it to the block schema. +To do this we'll use a `schemaEnhancer`. A schema enhancer is a function that receives an object with `formData` (the block `data`), the `schema` (the original schema that we want to tweak), and the injected `intl` (to aid with internationalization). Usually we would want to keep the schema enhancers in individual files per block, after which they can be imported to the {file}`index.js`. For this example we'll leave everything in the same file: -``` +```js import { defineMessages } from 'react-intl'; import { composeSchema } from '@plone/volto/helpers/Extensions'; import { defaultStylingSchema } from '@kitconcept/volto-light-theme/packages/volto-light-theme/components/Blocks/schema'; @@ -202,12 +201,11 @@ const applyConfig = (config) => { }; export default applyConfig; - ``` Finally, let's wire the width classes for our block in the file {file}`_relatedItems.scss`: -``` +```scss .block.relatedItems { margin-right: auto; margin-left: auto; @@ -249,12 +247,11 @@ Finally, let's wire the width classes for our block in the file {file}`_relatedI ``` +## Set themes for one block -## **Set Themes for One Block** +To demonstrate this feature, we'll add a custom list of themes just for the Related Items block, which will include one more theme called `Blue`. Add the property `themes` to the `relatedItems` block in the `blocksConfig` object: -To demonstrate this feature, we'll add a custom list of themes just for the Related Items block, which will include one more theme called `Blue`. Simply add the property `themes` to the `relatedItems` block in the `blocksConfig` object: - -``` +```js import { defineMessages } from 'react-intl'; import { composeSchema } from '@plone/volto/helpers/Extensions'; import { defaultStylingSchema } from '@kitconcept/volto-light-theme/packages/volto-light-theme/components/Blocks/schema'; @@ -336,8 +333,8 @@ const applyConfig = (config) => { }; export default applyConfig; - ``` + ## Conclusion Understanding how to extend VLT will help you take advantage of the system and quickly create consistent and flexible designs.