diff --git a/website/blog/2022-01-20-initial-setup.md b/website/blog/2022-01-20-initial-setup.md index f347d81e6..6b7d5aa7a 100644 --- a/website/blog/2022-01-20-initial-setup.md +++ b/website/blog/2022-01-20-initial-setup.md @@ -11,7 +11,7 @@ As is often the case when trying out something new, you might encounter some hic If you haven't already, be sure to read our official [Eightshift Docs](https://infinum.github.io/eightshift-docs/docs/welcome). -### Setup +## Setup To create Eightshift theme, navigate to `wp-content/themes` in your project and type the following in the terminal: @@ -35,7 +35,7 @@ OK, you went through the process, filled out all required information, but the t Congratulations, you've set up your Eightshift theme! -### Getting to know Eightshift dev tools +## Getting to know Eightshift dev tools After successfully setting up the theme and going through files, you'll notice this file structure is quite different from traditional WordPress themes and you may think to yourself: "Oh wow, what did I get myself into?" @@ -47,7 +47,7 @@ The final tip in this post is related to troubleshooting. Maybe you tried to add > Have you tried `composer dump-autoload` and re-running `npm start`? -### What's next in store? +## What's next in store? That's all for this post. In future posts we'll go through some more how-to examples like: - the difference between components and blocks diff --git a/website/blog/2022-01-21-components-and-blocks.md b/website/blog/2022-01-21-components-and-blocks.md index 6d592971a..a56be21a8 100644 --- a/website/blog/2022-01-21-components-and-blocks.md +++ b/website/blog/2022-01-21-components-and-blocks.md @@ -11,7 +11,7 @@ In this blog post, we'll give you a practical explanation about the difference b One of the things that is really confusing to newcomers is the difference between components and blocks. Let's break it all down. -### Component +## Component > A component is like a blank slate, a template without context. @@ -43,7 +43,7 @@ These attributes give you the option to modify the look of the component, so thi You can even add conditional logic to your options, e.g. to have the option for `imageWidth` visible only when `imagePosition` is set to left or right. And when `imagePosition` is set to top or bottom, it defaults to 100% width. -### Block +## Block So, what about blocks? Blocks can consist of one or more components and, most importantly, allow you to use them in the editor. Technically, blocks can consist of zero components, but we encourage you to build blocks from components because that increases the reusability. @@ -57,6 +57,6 @@ To do that, we'll add a new attribute called `featuredPosts` which will define w You may be wondering, can you have a block that allows you to use all options of the `card-simple` component? Of course! You can create a block that allows you to set all available options in the editor and manually add content to the image and heading. There are also block variations, which allow you to set up predefined attributes for a block. More about setting up block variations may be covered in one of the future posts. -### Conclusion +## Conclusion Hopefully, these examples helped you get a better understanding of the difference between components and blocks. It may take a bit more time or practical use to understand the difference and reasoning behind it. Our next post will walk you through downloading one of our components and blocks with WP CLI and modifying it. diff --git a/website/blog/2022-03-03-adding-blocks-wpcli.md b/website/blog/2022-03-03-adding-blocks-wpcli.md index ef45308df..bfcb6cf02 100644 --- a/website/blog/2022-03-03-adding-blocks-wpcli.md +++ b/website/blog/2022-03-03-adding-blocks-wpcli.md @@ -12,17 +12,17 @@ Although there are a few basic blocks available after creating a project, there These can be used out-of-the-box, but also as a good starting point if you need similar blocks in your projects. It will also speed up your development time since you don't have to build everything from scratch. -### Storybook +## Storybook Storybook allows you to preview how the components and blocks look and which options they have available. Since Storybook is interactive, you can try out most of the options. Think of it as a catalog with all custom blocks we've built and made ready for public use. Each entry in Storybook should have documentation that explains the block in more detail, along with implementation instructions. Before using any block, be sure to check `Dependencies` section. Although `Implementation` section lists all the necessary WP-CLI commands required to use a specific block or a component, it is recommended to check if you have the required dependencies ready in your theme. -### WP-CLI commands +## WP-CLI commands If you've read our [Initial Setup](/blog/initial-setup) post, you're already familiar with our custom WP-CLI commands. For implementing additional components, we have `wp boilerplate use_component` command. For blocks, we have `wp_boilerplate use_block` command. -### Adding new component and block in our project +## Adding new component and block in our project Let's say we need a Quote block in our project. After going through the documentation of the Quote block, we see that we have one dependency, and that is the Quote component. So, to make Quote block available in our project, we need two WP-CLI commands: @@ -35,7 +35,7 @@ You should do the commands in this order because Quote component doesn't have an The Quote block is now ready to use and available in your blocks list. You may use it as-is, or you may want to expand its functionalities with some additional attributes. More about that will be covered in the next blog post. -### Using Example block +## Using Example block If you want to build a block almost from scratch, you can use our Example block. This is a very simple block that generates all necessary files with some example options. To add an Example block to your project, use the following WP-CLI command: ```bash @@ -43,7 +43,7 @@ wp boilerplate use_block --name=example ``` Since our blocks use a predefined structure to make everything register automatically, adding Example block with WP-CLI will generate all required files. After it's added, feel free to rename the folder, as well as files with the name of your block and start modifying all the files. Simply replace "example" with the name of your block. -### Further reading +## Further reading Our documentation has all this covered in a lot more detail, so if you would like to better understand the structure of our blocks and components, here are some chapters covering these topics: diff --git a/website/blog/2022-03-04-modifying-blocks.md b/website/blog/2022-03-04-modifying-blocks.md index d38de9985..70ec1f295 100644 --- a/website/blog/2022-03-04-modifying-blocks.md +++ b/website/blog/2022-03-04-modifying-blocks.md @@ -13,12 +13,12 @@ In our previous post, we covered how to use Storybook and WP-CLI to add addition Since Eightshift Development kit is a starter theme, made for developers to jumpstart and speed up their development, you're welcome to modify files in it directly. There is no need to create a child theme to protect changes from updates. -### Modifying a block or a component? +## Modifying a block or a component? Because we used the Quote block in our previous post, we will continue using it as an example as it's a fairly simple one. One of the first questions you may ask yourself could be: "Should I modify a component or a block?". And the answer is - it depends. If you compare **_components/quote/quote.php_** (component) and **_custom/quote/quote.php_** (block), you'll notice that most of the HTML code is inside the component, while the block pretty much only renders the Quote component inside a wrapper. This example will walk you through the whole process of adding a new attribute and its options to a block. -### What will we do? +## What will we do? We want to style the block and add a new feature. An option to choose a color theme for the Quote block. These are the specs: - each Quote block has a background with rounded corners @@ -29,7 +29,7 @@ We want to style the block and add a new feature. An option to choose a color th To better help you visualize, this is how the Quote block should look like after making these changes, showcasing all three color theme variations: ![Color Theme Examples](/img/blog/color-theme-examples.png) -### Adding background +## Adding background Initial background styling is fairly straightforward. Navigate to **_src/Blocks/components/quote/quote-style.scss_** and paste the following code inside `.quote` class: @@ -45,7 +45,7 @@ For now, we will add a simple light grey background to see how it looks. We'll r You'll notice that the changes are visible both in the editor and on the frontend. Since the Gutenberg editor adds some additional markup, sometimes you'll need to add additional styling only for the editor. In case we need to override something in the editor for our Quote component, we would simply create **_quote-editor.scss_**. -### Adding new colors to your project +## Adding new colors to your project Because the theme currently doesn't have all the required colors, we need to add additional colors which will be used for the color theme feature. We will use the colors already defined in the manifest for icon color, but we need to add lighter variations of those colors to use them for the background. Navigate to your global manifest, which is located inside **_src/Blocks/manifest.json_** and add the following values inside `colors`: ```json @@ -66,7 +66,7 @@ Because the theme currently doesn't have all the required colors, we need to add } ``` -### Adding a new attribute and options to manifest +## Adding a new attribute and options to manifest For editors to be able to choose which color theme to use for the Quote block, we need to define an attribute for it in the manifest. Navigate to **_src/Blocks/components/quote/manifest.json_** and add the following value inside `attributes`: @@ -90,7 +90,7 @@ After that, since we want to have a fixed number of options, we need to define a } ``` -### CSS variables +## CSS variables Our next step is to add CSS variables to the Quote component's manifest. Inside **_manifest.json_**, on the same level as `attributes`, add the following code: ```json @@ -139,7 +139,7 @@ As you can see, the variable name is the same one we used when defining backgrou } ``` -### Outputting CSS variables in editor +## Outputting CSS variables in editor To make our color theme visible in editor, we have to add few lines of code to **_src/Blocks/components/quote/components/quote-editor.js_** file. First, we need to import a few functions. We need `useMemo` from **_react_**, `outputCssVariables` and `getUnique` from **_@eightshift/frontend-libs/scripts_** and finally, we need data from the global manifest. After importing these and defining a unique constant, your code should look like this: @@ -171,7 +171,7 @@ return ( If you try adding a Quote block in the editor, you should notice that it now has a light blue background with a quote icon in a darker shade of blue. This is the default value for the `quoteColorTheme` attribute we added in the component's manifest. -### Outputting CSS variables in the PHP template +## Outputting CSS variables in the PHP template The PHP template for the Quote component is located in **_src/Blocks/components/quote/quote.php_**. This process is similar to the one described above, it's just written in PHP. All helper methods we need for this are contained inside the `Components` class, which is already included in this file. Similar to the JS template, we need a unique value, assign it to `data-id`, and output CSS variables. After adding these, the code should look like this: @@ -195,7 +195,7 @@ $unique = Components::getUnique(); > Both PHP and JS have the same helpers to make writing code for editor and front view as similar as possible. -### Adding options +## Adding options After adding these snippets, you should already see that your block is using the blue color theme, which we defined as the default value for `quoteColorTheme` in the manifest. We want to have an easy way to change the color theme in the editor. Now we'll add a new option which will do just that. We will add these options in **_src/Blocks/components/quote/components/quote-options.js_**. Again, we will start with the imports we will need. First one is `__` from **_@wordpress/i18n_** package. Additional imports we need are from **_@eightshift/frontend-libs/scripts_**, so we will just add those to the list. @@ -251,7 +251,7 @@ The Color Theme option should now be visible and fully functional inside the Quo ![Color Theme Options](/img/blog/color-theme-options.png) -### Adding transitions in the editor +## Adding transitions in the editor The options work, but you may notice there is no transition in the editor. It is not necessary but will improve the user experience. Since we do not need transition effects on the frontend, we can add these CSS rules only to the editor. To do that, we start by creating **_quote-editor.scss_** file inside **_src/Blocks/components/quote_** folder. @@ -270,7 +270,7 @@ Because we've added a new file, we have to run `npm start` again. Now the transi ![Color Theme Change](/img/blog/color-theme-change.gif) -### Closing thoughts +## Closing thoughts In this post, we've covered the whole process of adding a new attribute. It involves a lot of steps and things to keep in mind, but once you get used to it, you'll be able to add quite powerful features to your blocks. diff --git a/website/blog/2022-04-08-adding-fonts.md b/website/blog/2022-04-08-adding-fonts.md new file mode 100644 index 000000000..76a9d2137 --- /dev/null +++ b/website/blog/2022-04-08-adding-fonts.md @@ -0,0 +1,205 @@ +--- +title: Adding fonts +description: An intro to adding fonts to your project. +slug: adding-fonts +authors: iobrado +date: 2022-04-12 +tags: [eightshift, boilerplate, fonts] +hide_table_of_contents: false +--- + +Every project is unique. Logo, colors, fonts, etc. are what define the visual identity of your website. In this post, we'll cover adding fonts to a project. + + +## Importing fonts into your project +[Our documentation](/docs/basics/fonts) covers the necessary steps to add a font to your project, but here we'll cover the process in a bit more detail. To start, we need a font (or two). For this example, I'll use **_Source Sans Pro_** and **_Noto Serif_** which I've downloaded from [Google Fonts](https://fonts.google.com/). They are in the `.ttf` format (you may find some which are `.otf`, which will work in the same way), so you need to convert them to `.woff` and `.woff2`. Whatever approach you use is okay - we recommend the following tools: +- [Convertio](https://convertio.co/ttf-woff/) +- [Cloud Convert](https://cloudconvert.com/ttf-to-woff) +- [Everything Fonts](https://everythingfonts.com/ttf-to-woff) +- [Transfonter](https://transfonter.org/) + +> Just make sure you have the proper license for the fonts you are converting. + +Fonts should go inside your theme's **_/assets/fonts_** folder. Copy the fonts you want to use there. You will also notice that this folder contains an **_index.js_** file, used to import fonts into your project. Here's an example of how I imported my fonts: +```js +// SourceSansPro WOFF +import './SourceSansPro-Bold.woff'; +import './SourceSansPro-BoldItalic.woff'; +import './SourceSansPro-Italic.woff'; +import './SourceSansPro-Regular.woff'; +import './SourceSansPro-Light.woff'; +import './SourceSansPro-LightItalic.woff'; + +// SourceSansPro WOFF2 +import './SourceSansPro-Bold.woff2'; +import './SourceSansPro-BoldItalic.woff2'; +import './SourceSansPro-Italic.woff2'; +import './SourceSansPro-Regular.woff2'; +import './SourceSansPro-Light.woff2'; +import './SourceSansPro-LightItalic.woff2'; + +// NotoSerif WOFF +import './NotoSerif-Bold.woff'; +import './NotoSerif-BoldItalic.woff'; +import './NotoSerif-Italic.woff'; +import './NotoSerif-Regular.woff'; + +// NotoSerif WOFF2 +import './NotoSerif-Bold.woff2'; +import './NotoSerif-BoldItalic.woff2'; +import './NotoSerif-Italic.woff2'; +import './NotoSerif-Regular.woff2'; +``` + +> If you don't need to support IE11, don't include `.woff` files. This will save you some bandwidth. + +To add these fonts as your base font and secondary font, go to the global manifest located in **_/src/Blocks_** and add the following inside `globalVariables`: +```json +"globalVariables": { + // ... + "baseFont": "SourceSansPro", + "secondaryFont": "NotoSerif", + // ... +} +``` + +Next, you can create a new file called **__typography.scss_** inside your **_/assets/styles/parts/utils/_** folder and add the following: + +```scss +@include font-face(global-settings(baseFont), 'SourceSansPro-Light', 300); +@include font-face(global-settings(baseFont), 'SourceSansPro-LightItalic', 300, italic); +@include font-face(global-settings(baseFont), 'SourceSansPro-Regular', 400); +@include font-face(global-settings(baseFont), 'SourceSansPro-Italic', 400, italic); +@include font-face(global-settings(baseFont), 'SourceSansPro-Bold', 700); +@include font-face(global-settings(baseFont), 'SourceSansPro-BoldItalic', 700, italic); + +@include font-face(global-settings(secondaryFont), 'NotoSerif-Bold', 700); +@include font-face(global-settings(secondaryFont), 'NotoSerif-BoldItalic', 700, italic); +@include font-face(global-settings(secondaryFont), 'NotoSerif-Italic', 400, italic); +@include font-face(global-settings(secondaryFont), 'NotoSerif-Regular', 400); +``` +If you would like to know more about the `font-face` mixin, you can take a look at our [Sass documentation](/sass). + +Because this is a new file, we have to include it. You can do that inside **_/assets/styles/parts/\_shared.scss_** file: +```scss +// Project specific. +@import 'utils/shared-variables'; +@import 'utils/typography'; +``` + +Run `npm start` to rebuild your **_public_** folder and assets. If you did everything correctly, your build should pass and you will see your fonts inside the **_public_** folder. + +## Using only one font in a block + +There are multiple ways of using fonts in a block. The simplest use case is if you have only one font you want to use for that specific block. In this case, we want the Heading block to only use _Noto Serif_. + +To make our secondary font available for use, we need to first define it as a CSS variable. We can do that in **_/assets/styles/parts/utils/\_shared-variables.scss_**. The base font is already defined there, so all we need to do is add our secondary font definition below it. + +To make things a bit more consistent, we may also want to rename `--global-font-family` CSS variable to `--base-font-family`. Just don't forget to search/replace this new variable name across your project! Please note that the fallbacks for the fonts can be anything, this is just an example. Once we're done, it should look like this: +```scss + --base-font-family: var(--global-base-font), -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, + Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; + + --secondary-font-family: var(--global-secondary-font), -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, + Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; +``` +After defining the `--secondary-font-family` CSS variable, we can go to **_/src/Blocks/components/heading/heading-style.scss_** and add the following rule to the `.heading` class: +```scss + font-family: var(--secondary-font-family); +``` + +And that's it! The Heading block will now use the _Noto Serif_ font. + +## Adding a font picker + +In some cases, you may want to give users the option to choose between fonts that they want to use in their block. For this example, we'll use the `paragraph` block where we want users to have both _Source Sans Pro_ and _Noto Serif_ available. + +First step is to add a new attribute, options and CSS variable values in **_/src/Blocks/components/paragraph/manifest.json_**: +```json +// ... + "attributes": { + // ... + "paragraphFontFamily": { + "type": "string", + "default": "base" + } + }, + "options": { + // ... + "paragraphFontFamily": [ + { + "label": "SourceSansPro", + "value": "base" + }, + { + "label": "NotoSerif", + "value": "secondary" + } + ], + // ... + } +``` + +After defining the new attribute and options for the font family, we now have to add a variable to **_manifest.json_**. We can add it to the `variables` object. This approach is slightly different from the one explained in the [Modifying blocks](/blog/modifying-blocks-color-theme) blog post. Here we can use `%value%` wildcard to dynamically add the selected value to our CSS variable. +```json +"paragraphFontFamily": [ + { + "variable": { + "paragraph-font-family": "var(--%value%-font-family)" + } + } +] +``` + +The next step is to go to **_/src/Blocks/components/paragraph/components/paragraph-options.js_** and add a control for the new font family option. The first thing we can add is a new attribute that will allow us to toggle showing the Paragraph font family option on other blocks which are using the Paragraph component. There might be a case where we want only one font family, so this option may come in handy in some other blocks. +```js +const { + setAttributes, + //... + showParagraphFontFamily = true, + } = attributes; +``` + +After that, we need to fetch either the saved attribute value or get the default one from the manifest. We can do that with the `checkAttr` helper, adding it just below `paragraphColor` and `paragraphSize`. +```js + const paragraphFontFamily = checkAttr('paragraphFontFamily', attributes, manifest); +``` + +Now we have to add an actual control to the options panel which will allow us to choose between fonts. +```js + return ( + // ... + {showParagraphFontFamily && + } + value={paragraphFontFamily} + options={getOption('paragraphFontFamily', attributes, manifest)} + onChange={(value) => setAttributes({ [getAttrKey('paragraphFontFamily', attributes, manifest)]: value })} + isClearable={false} + isSearchable={false} + simpleValue + /> + } + // ... + ); +``` + +The control for selecting a font should now be available under Paragraph options. Saving the choice now works, but the font stays the same both in the editor and on the frontend. + +![Font Picker](/img/blog/font-picker.png) + +The final step we need to make this work is to add a CSS rule that consumes our variable to **_/src/Blocks/components/paragraph/paragraph-style.scss_**: +```scss +.paragraph { + // ... + font-family: var(--paragraph-font-family, var(--base-font-family)); + // ... +} +``` + +After adding this single line of CSS code, your new option for selecting fonts will now be fully functional. + +## Closing thoughts +Adding fonts to a project is something you will usually only do when setting up a new project and then forget about it. As you could see in this blog post, this isn't a complicated process, but it has a specific set of steps that have to be taken in order for custom fonts to work in your project. + +Of course, there are other ways to include fonts in your project, but the described process is what we recommend and use. This is the (Eightshift) Way. diff --git a/website/static/img/blog/font-picker.png b/website/static/img/blog/font-picker.png new file mode 100644 index 000000000..d98127a4f Binary files /dev/null and b/website/static/img/blog/font-picker.png differ