This project is no longer maintained. Please use https://github.com/sayhellogmbh/hello-fse instead.
This is a boilerplate WordPress theme by say hello. It has an object oriented php architecture and comes with some very handy build workflows for CSS and JavaScript.
This code is distributed under the GNU General Public License v3.0. Or in short: it's open source. You are free to use this starter theme or only parts of it for personal and commercial use!
node and node package manager npm are required to run the build commands.
Please visit https://nodejs.org/en/download/ and download the latest LTS version of nodeJS.
This theme comes with some very handy gulp tasks to make your life much easier.
You can install the packages using npm install. The current required versions of Node and NPM are included in the package.json file.
$ cd path/to/your/project/
$ npm installAfterwards you can use the following command to start the default gulp tasks.
$ npm start(Installed node modules are explicitly excluded from the git repository.)
This theme supports WordPress from version 5.9 onwards. Older versions of WordPress are not supported because of the theme's basis on Full-Site Editing.
The theme is currently dependent on the Advanced Custom Fields plugin. This plugin must be installed and activated before the theme is activated.
Set WP_DEBUG to true in wp-config.php in the development environment. This will load the unminified and sourcemapped assets (JavaScript and CSS) for easier debugging.
define('WP_DEBUG', true);If you need to work in debug mode but suppress PHP notices and warnings, you can additionally turn them off.
define('WP_DEBUG_DISPLAY', false);You can keep a log of all notices, warnings and errors in wp-content/error.log by turning on the debug log.
define('WP_DEBUG_LOG', true);This theme is set up to use the Full Site Editing feature built into WordPress since version 5.8 and extended in WordPress 5.9. Block templates are created containing a series of blocks and the theme contains a few block template parts, where a combination of blocks is used across multiple templates.
The essential block templates are located in the block-templates folder. Block template parts are located in the block-template-parts folder.
PHP files which were formerly in use for templating - like archive.php or single.php - will be ignored if full-site editing is active.
### Free online course for users and developers
For more information and a free online-course about Full Site Editing, which will give you a good grounding in the coding techniques implemented here, please visit fullsiteediting.com. The site is maintained by WordPress Core contributor Carolina Nymark and is not affiliated with Say Hello.
The theme.json file was introduced with WordPress 5.8 as part of the technology for Full Site Editing. This file contains settings for controlling both the editor and some of the site output.
assets/settings.json is a non-standard settings file, which forms part of the specific logic of Hello Roots. There are shared settings between CSS and JavaScript files which are stored inside this file. You can import them into any JavaScript module (import settings from '../../../../../assets/settings.json';), use them inside any scss file (for example: $my_easing_speed: $easing_speed;), or load them into PHP using the methods getThemeJson or getSettings in the Theme class.
You can also load the contents of the theme.json file into SCSS and/or JavaScript by the same means. For example, import theme_json from '../../../../assets/theme.json';. This will currently throw an error from sass because of the $schema entry key. If you really need to import theme.json then remove the $schema entry. (This entry is valuable because it validates the structure of the JSON file automatically in your IDE. Further details are here.)
The import functionality in SCSS and JavaScript is part of the build process. It uses gulp-sass-import-json by Renat Gafarov.
(In the theme development community, it's common to refer as the various settings in dot notation; for example settings.color.background.)
settings.custom.spacing.unit: the standard unit from which many spacings and scalings are calculated. Uses the WordPressblockGapstandard CSS property--wp--style--block-gapby default.settings.custom.spacing.outer-gutter: the gap to the left and right of the content blocks (usually only visible in mobile).
Hello Roots delivers a standard set of templates and template parts for the most common requirements. This can be (and should be) modified to suit the project and theme.
The HTML structure of the templates is kept as simple as possible in the unchanged version of the theme. The masthead is the banner across the top of the page which usually contains the navigation, and the footer is the section at the bottom of each page. Each of these areas are contained within their own template parts.
The main element contains the main body of the page content and the editorially-created content is output by the post content block.
Direct children of the post content block are assigned a gutter to the left and right, so that they don't hit the edge of the screen at smaller screen sizes. Direct children of the post content block which have been assigned with full-width alignment receive a negative margin on the left and right to offset the gutter. The gutter is defined in the custom spacing section of theme.json.
The footer is forced to the bottom edge of the browser on shorter pages through the use of display: flex on the .wp-site-blocks element.
.wp-site-blocks
.c-masthead
.c-main
.wp-block-post-content
.c-footer
By default, WordPress wraps full-site-editing template parts with a div. The code in the Theme removes this element, in order to maintain a clean HTML structure.
Assigning a class name to the template part block using the CSS class name field in the Editor will not work. If a template part needs to contain a wrapper with a specific class name, this should be applied using a group block inside the template part file. (e.g. the masthead.)
The current beta version 3.2 of the translation plugin Polylang Pro supports the direct translation of template parts (but not templates). If the fixed templates in the theme contain a string which may need to be translated, move this section to its own template part.
Breakpoints are read in from assets/settings.json by Sass, and generate CSS properties like --constraint-wide. These are used in your own CSS. The values used by WordPress Core, however, come from the content width settings in your theme.json file.
WordPress loads external content - e.g. responsive images or external video embeds - at an appropriate size using the $content_width variable. Since the introduction of theme.json, this variable is set from the value of settings.layout.contentSize in the theme.json file. Modify the value of this entry based on the standard width of a content element in the single blog post view.
In order to allow wide- and full- width content, ensure that the correct value is set for settings.layout.wideSize.
If you want to use CSS properties like --constraint-wide in your CSS, then make sure that the same breakpoint values for narrow and wide are set in settings.json as you have set in settings.layout.contentSize and settings.layout.wideSize.
This theme uses an ITCSS architecture together with the BEM naming convention. All .build/assets/styles/*.scss files will be converted to sourcemapped assets/styles/{$name}.css files. Minified versions (without source mapping) will also be generated.
The Package Class Assets enqueues these files directly.
- admin-editor.min.css is loaded in the Block Editor. This file is generated from .build/assets/styles/admin-editor.scss.
- admin.min.css is loaded in all views of WordPress Admin. The contents of this file should not contain styling for the blocks in the Block Editor. This file is generated from .build/assets/styles/admin.scss.
- ui.min.css is loaded in the frontend of the website. This file is generated from .build/assets/styles/ui.scss.
The SCSS variable $context is defined in admin.scss (value admin), admin-editor.scss (value edit) and ui.scss (value view) appropriate to each context, so that the mixins context-view, context-edit and context-admin can generate the CSS appropriately for the current context. For example:
.wp-block-image {
vertical-align: middle;
}
@include context-view() {
.wp-block-image {
margin-top: 1rem;
margin-bottom: 1rem;
}
}Note that the call to @include context-view() cannot be defined within the .wp-block-image definition. It must be included as a separate section. This is due to the CSS namespacing which occurs in the gulp-editor-styles process.
The CSS will be generated with CSS Custom Properties in the generated stylesheets. The (JavaScript-based) Ponyfill css-vars-ponyfill (source) is included for IE11 support in the frontend. (Not in the admin area! Support for Internet Explorer is being phased out of WordPress Admin.)
CSS Custom Properties are currently defined on the body element. This is in order to use the same logic as WordPress Core. If you need to support IE11 through css-vars-ponyfill or make an alias for a CSS Custom Property generated by WordPress (e.g. colours) which is applied to body, then amend the definitions to ensure they're applied to both body and :root.
For example:
body,
:root {
--my-custom-property1: #f00;
--my-custom-property2: var(--wp--preset--color--red);
}The colour selection for blocks in the editor is defined within the settings.color.palette entry of theme.json. These values can also be overridden for specific block types. (e.g. if you only want to allow the selection of black or blue on core/heading blocks.) WordPress generates CSS custom properties for the values: for example, --wp--preset--color--red. Hello Roots does not interfere with the generation of these class names.
If you need to define colours which generate CSS custom properties, but which are not to be displayed to the user for editorial selection, then add them to the definitions for theme_colors in assets/settings.json. The SCSS file colors.scss in the overrides folder generates CSS custom properties with the syntax --sht--color--{name} or --sht--color--{name}-{variant} for use in theme CSS.
Gulp uses the gulp-editor-styles Node Module to automatically parse and wrap the CSS in an appropriate scope (.editor-styles-wrapper) for the Gutenberg editor. Any CSS definition assigned to body in CSS which will be loaded in the editor will be converted to use this class name.
In SCSS:
body {
background-color: red;
}Output:
.editor-styles-wrapper {
background-color: red;
}The stacking placeholder selector %h-stack is used via @extend to create a stack of elements, in which the top and bottom margins are initially set to zero. Then, every element which has a predecessor receives a top margin. This allows any element containing children to neatly and regularly “stack“ its children with equal spacing, with one simple CSS rule. This rule can be used widely throughout the site, avoiding unnecessary re-definition by referring to the same placeholder selector every time.
%h-stack uses the CSS custom property --wp--style-block-gap which is implemented by WordPress Core. (More information about Block Gap.) In the event that a specific element needs the same logic to be applied but with a different spacing, then use the %h-stack rule and set the --wp--style-block-gap CSS custom property to the value you need. You can alternatively use one of the pre-defined rules like %h-stack--medium, which do the same thing but which allow a regular, logically-scaled layout logic.
.wp-block-post-content {
@extend %h-stack;
}
.c-main {
@extend %h-stack;
}
ul {
@extend %h-stack;
--wp--style-block-gap: 5px;
}
.c-random-component {
@extend %h-stack--medium;
}The Theme is provided with built-in SCSS and Webpack support for developing Gutenberg blocks using React. There is a specific PHP Gutenberg Package for some functionality.
Blocks built with JavaScript are usually programmed in JSX syntax. These are converted to ES5 using Babel and bundled using Webpack.
The NPM package @wordpress/dependency-extraction-webpack-plugin intelligently recognises dependencies in the JavaScript from the @wordpress namespace, for example import { registerBlockType } from '@wordpress/blocks';. This Webpack plugin defines the WordPress block editor scripts as external dependencies within the context of block editor scripts. This means that dependencies are not compiled into the block scripts. (Because they are already loaded by WordPress' own scripts in the editor environment.)
The css-loader and css-loader NPM packages provide support for CSS in JavaScript. (If you must! 😉) This support is primarily intended for use in individual frontend scripts, not as a generic solution for adding CSS to the frontend. Create all CSS for the editor through the SCSS build process.
import 'style.css';This theme uses ES6 modules which are converted to ES5 using Babel and bundled using Webpack. The Package Class Assets enqueues the resultant files. For example: all .build/assets/scripts/ui/*.js files will be bundled to assets/scripts/ui.js. A minified version assets/scripts/ui.min.js will also be generated. Block editor scripts are enqueued by the Gutenberg Package.
There is a built in Font loading process using base64-encoded woff/woff2 fonts, which are stored inside the local storage of the browser when a page on the site is first loaded by the browser. This helps to avoid FOUT problems.
Assuming that the fonts you're using are licensed for use in this way, convert the fonts to base64-encoded WOFF and WOFF2 CSS files using Transfonter and then add the code to the files in the assets/fonts folder. Generate the WOFF and WOFF2 versions separately, as you'll need individual CSS files.
These files are then loaded by JavaScript injected using the Assets Package and stored in the browser's LocalStorage. The script checks the asset version number. If you need to force a new version of the font files for all site visitors, then update the value of theme_fontver in the settings.json configuration file. Only the appropriate file version for the current browser (usually WOFF2) is actually loaded.
(If you don't need to support IE11, then you don't need WOFF. WOFF2 is supported by all modern browsers.)
The build process uses LiveReload to refresh your browser when you modify any JavaScript or CSS files.
If you are using Google Chrome there is a pretty helpful extension: Chrome LiveReload
SVG support and sanitization was formerly handled directly by the Theme. This feature was removed in 2020 in favour of https://wordpress.org/plugins/safe-svg/. Install and use this plugin if users need to upload and integrate SVGs to the site through the editor and the media manager.
The build process will automatically parse and minify any SVG files added to the assets/img/ folder using the gulp-svgmin NPM package if the gulp watcher is running. Link to the minified versions in your CSS.
- Nico Martin
- Mark Howells-Mead
- Joel Stüdle
Dimitri Suter(Dimitri is a former contributor)