diff --git a/website/docs/basics/architecture-concepts.md b/website/docs/basics/architecture-concepts.md new file mode 100644 index 000000000..1f3e110b8 --- /dev/null +++ b/website/docs/basics/architecture-concepts.md @@ -0,0 +1,247 @@ +--- +id: architecture-concepts +title: Architecture concepts +--- + +## Project structure + + +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) + +Eightshift Development Kit follows a strict project structure to support autoloading, dependency injection and `wp boilerplate` commands, as well as conventions to increase codebase understanding between developers. As an added benefit, following this structure and conventions makes your codebase more consistent and organized. + +While Eightshift Development Kit provides required theme files and common theme files such as `style.css` and `functions.php`, they're used differently to what you might expect if you've worked with WordPress themes previously. For instance, `style.css` is used only to register theme metadata, and doesn't contain any actual styles, as they're built using Webpack and use cache busting. `functions.php` simply bootstraps the execution lifecycle. We also provide very basic template partials, such as `single.php`, which you can acommodate to your needs. An idea to consider is replacing some of them with pages that are editable in Gutenberg. + +While you'll find some additional configuration files such as `webpack.config.js` in the project root, the majority of your projects codebase should live in the `src` directory, which is autoloaded via Composer following PSR-4 conventions. This implies that every directory under `src` is a namespace under your base namespace (which is your project name), and PHP files inside of those directories are classes in that namespace, with exceptions for filenames that aren't in `StudlyCase`. + +An Eightshift Development Kit convention is to structure namespaces around features and functionality, so for instance, all custom post types would be part of the `ProjectName\CustomPostType` namespace. + +## Object-oriented paradigms + +Eightshift Libs is entirely object-oriented, providing abstract classes for internal library functionality, interfaces you can use to implement certain classes to make use of Eightshift Development Kit features, as well as concrete class implementations for use in projects. + +Our use of OOP allows you to extend, modify or even replace Eightshift Development Kit functionality safely, without breaking compatibility or harming your project. + +One of the most important interfaces in Eightshift Libs is the `ServiceInterface`. Classes that implement it are called service classes. This isn't a common pattern in PHP OOP. In Eightshift Development Kit, a service class represents a part of the project's functionality and has a `register` method that sets up the action and filter hooks for the service. If you need to add an action or a filter, you should do that in a service class. All your service classes are automatically loaded and can have dependencies injected using dependency injection. + +To ensure there are no naming collisions caused by Composer dependencies, we use the [Imposter Composer plugin](https://github.com/infinum/imposter-plugin) to contain them in the `{ProjectName}Vendor` namespace. This comes with a few caveats which you should be aware of, and about which you can read more in the [namespaces chapter](namespaces). + +Read more about [namespaces and Imposter](namespaces), [extending classes and service classes](extending-classes), and [dependency injection and autowiring](autowiring). + +## Blocks and Components + +While Blocks and Components will be covered in much more detail in the [Blocks chapter](blocks), it's worth getting acquainted with the concepts from the start. + +In Gutenberg, Blocks are an abstract unit for structuring content. The same applies in Eightshift, with an additional concept of _Components_, which are abstract units for structuring blocks and layouts. + +Components are mostly similar to Blocks, with a few key differences: +* Components can not be inserted by users in Gutenberg, and are not registered as block types +* Components can be rendered in any context using the `Components::render` method, with arbitrary attribute values passed to them +* Blocks are usually only rendered using the render callback provided when registering the block + * Note that in the Eightshift Development Kit, the render callback is provided for you by Eightshift Libs. It automatically adds the wrapper if neccessary and sets up your block view. +* Components don't implement the `{blockName}-block.js` file + +Blocks and Components have the same structure, which makes extracting components from existing blocks trivially easy. + +Components can be _composed_ into a block. In other words, blocks can consist out of zero or more components. Component composition is handled in the block manifest, allows you to avoid using InnerBlocks to include functionality shared with other blocks, and serializes component attributes to the block using prefixed attributes for each component instance depending on your manifest definitions. + +To learn more about the differences between blocks and components, read [Igor's blog post on Components and blocks](../../blog/components-and-blocks). To learn how to use blocks and components to build your projects, read the [Blocks chapter](blocks). + +## The Manifest + +`manifest.json` files contain metadata, configurations and variables. + +Every Eightshift project has one global `manifest.json` file stored in `src/Blocks/manifest.json`, which contains global settings, properties, and variables. + +Furthermore, every Eightshift block, component, and variation has its own manifest file which is used to provide data required for block registration, such as a list of attributes, the block name, and the template for the inserter example. These local manifest files allow you to define arrays of options for attribute values that your blocks or components can consume. Manifest files also allow you to define relationships between attribute values and CSS variable values, which allows you a great deal of power when styling your blocks and components, as well as saves time as you don't have to provide conditional CSS classes. + +To learn more about the [global manifest](blocks-global-manifest.md), [block manifest](block-manifest.md), [component manifest](blocks-component-manifest.md) and using [the manifest to provide CSS variables for use in block styling](blocks-styles.md), read the respective articles in the [Blocks chapter](blocks-important). For information about manifest structure, refer to the manifest schemas available in Eightshift Frontend Libs and linked to in the manifest files. + +## The directory structure in detail + +Your project might contain a different set of namespaces and classes in the `src` folder, depending on what you've included using wp boilerplate commands. +By default, your project will include the `Blocks`, `Config`, `Enqueue`, `Main`, `Manifest` and `Menu` namespaces. You can include classes from Eightshift Libs to provide additional functionality manually or using wp boilerplate. + +This chapter also doesn't cover all of the namespaces and classes in Eightshift Libs, or their use. Check out the source code documentation for all available namespaces and classes. + +- src + - Blocks + - assets + - components + - custom + - variations + - wrapper + - Columns + - Config + - CustomMeta + - CustomPostType + - CustomTaxonomy + - Enqueue + - Admin + - Blocks + - Theme + - Exception + - Helpers + - I18n + - Main + - Manifest + - Media + - Menu + - ModifyAdminAppearance + - Plugin + - Rest + - ThemeOptions + - View +- .storybook +- .gitignore +- .eslintignore +- .eslintrc +- .stylelintrc +- babel.config.js +- composer.json +- composer.lock +- package-lock.json +- package.json +- phpcs.xml.dist +- postcss.config.js +- README.md +- webpack.config.js + +#### Blocks + +The Blocks namespace contains the Blocks class used for block registration. This directory also contains shared assets, components, blocks, variations, and the wrapper. + +Read about blocks in detail in the [Blocks chapter](blocks). + +#### Columns + +This namespace contains all the custom admin listing columns hooks in your project. These include listing column hooks for post types, taxonomy, and user lists, such as `manage_{$post_type}_posts_columns`. + +#### Config + +The Config class provides getter methods for your project's configuration, such as `getProjectName` or `getProjectVersion`. + +#### CustomMeta + +This class contains all the custom meta hooks for your project. + +#### CustomPostType + +This namespace contains classes that register all custom post type hooks for your project. For better code consistency and to save time on boilerplating, Eightshift Development Kit provides an example class implementation you can use with `wp boilerplate create_post_type`. + +#### CustomTaxonomy + +This namespace contains classes that register all custom taxonomy hooks for your project. For better code consistency and to save time on boilerplating, Eightshift Development Kit provides an example class implementation you can use with `wp boilerplate create_taxonomy`. + +#### Enqueue + +These Enqueue namespace classes handle loading JavaScript and CSS assets, depending on the location you want to use it: +- **Admin** - Used in the admin (not block editor) panel. You can find the files inside the `assets` folder with the `-admin` suffix. +- **Blocks** - Used in the block editor. You can find the files inside the `src/Blocks/assets` folder. As blocks are complicated, we have files loaded only in the admin-editor part of the project, those files have an `-editor` suffix. The rest of the files with no suffix load on the admin-editor part and the project's front end. +- **Theme** - Used in the theme (frontend) part of your project. You can find the files inside the `assets` folder with no suffix. You would use these files for the assets related to your project that is not associated with components and blocks. These files are rarely used, as styles and JavaScript functionality are usually provided at component, block, or wrapper levels. + +Using any of these classes is optional, and you can use only what you need. The `wp boilerplate setup_theme` command will set up all of the three classes already implemented. Keep in mind that Enqueue classes work in combination with the Webpack build of your project. + +All of the asset files mentioned are prefixed with `application`. If you don't like the prefix, you can change it by providing project overrides for constants used in Eightshift Libs. If you change the file names, you must make changes to the Webpack build process as well. For modifying the Webpack configuration, read the [Webpack chapter](webpack). + +#### Exception + +This namespace contains all exceptions that can be thrown from the project. + +#### Helpers + +All the backend helpers provided by Eightshift Libs are part of the Helpers namespace. Generally, you can use them from Eightshift Libs without extending or modifying them. + +#### I18n + +Classes in this namespace are used to define all hooks related to internationalization and localization. For more information about i18n and l10n, check out [Tips and tricks](tips-tricks). + +#### Main + +The Main namespace contains the `Main` class, which sets up the dependency injection container and autowiring using `AbstractMain` and `Autowiring` classes. For most projects, `Main` can be used automagically without any work on your part, but as with all of the Eightshift Development Kit, you can extend it to suit your needs. + +You can provide manual service classes here as well. Learn more in the [autowiring chapter](autowiring). + +#### Manifest + +The Manifest namespace provides the `manifest.json` file location and helpers to return the full path for a specific asset. Learn more about the manifest in the [manifest chapter](manifest). + +#### Media + +The Media namespace is used to add custom implementations for media, such as adding custom image sizes, enabling SVG image support, etc. By default, it registers theme support for title tags, HTML5 and post thumbnails. + +#### Menu + +This class is used to register menu positions. + +#### ModifyAdminAppearance + +This class is used to change admin appearance. We use it to change the admin color palette depending on the environment. + +#### Plugin + +This namespace is used only in the plugin boilerplate and holds classes required for activation and deactivation of the plugin. + +#### Rest + +The Rest namespace provides classes for handling REST API fields and routes. This is covered in more detail in the [REST chapter](rest). + +#### ThemeOptions + +This namespace is used to add admin menu configuration panels such as _Theme Options_, usually using ACF. + +#### View + +This namespace is used to add filters used when escaping unsafe tags using `wp_kses_post` and `wp_kses` functions. + +#### .storybook + +This folder contains all of the files necessary to run the storybook in your project. Read more [about the Storybook project](https://storybook.js.org/). + +#### .gitignore + +As the name implies, this file is used to define restrictions to which files Git watches. Read more [about Git](https://git-scm.com/). + +#### .eslintignore + +Defines files and folders which ESLint should ignore when linting. + +#### .eslintrc + +Provides definitions used for linting JavaScript files. Read more [about ESLint](https://eslint.org/). + +#### .stylelintrc + +Provides definitions used for linting SCSS/CSS stylesheets. Read more [about Stylelint](https://stylelint.io/). + +#### babel.config.js + +Provides Babel configuration, which determines how your JavaScript code will be compiled, what standard you will use, and much more. Read more [about Babel](https://babeljs.io/). + +#### composer.json + +Contains a list of your project's Composer dependencies, as well as project metadata and configuration. Dependencies can be added and installed using `composer install`. Read more [about Composer](https://getcomposer.org/). + +#### composer.lock + +Lock files are used to set the package version to the exact release. This ensures that everyone has the same package version when installing. + +#### package-lock.json + +The same as `composer.lock`, but for node_modules. + +#### package.json + +Contains a list of your project's npm dependencies, as well as project metadata and configuration. Dependencies can be added and installed using `npm install`. Read more [about npm](https://nodejs.dev/). + +#### phpcs.xml.dist + +Provides definitions used for linting PHP files. Read more [about PHPCS](https://github.com/squizlabs/PHP_CodeSniffer). + +#### postcss.config.js + +PostCSS works in collaboration with Webpack and defines what additional plugins you are going to use when building your CSS files. Read more [about PostCSS](https://postcss.org/). + +#### webpack.config.js + +`webpack.config.js` provides Webpack configuration, used when building your JavaScript and CSS files. This is covered in more detail in the [Webpack chapter](webpack). diff --git a/website/docs/basics/autowiring.md b/website/docs/basics/autowiring.md index fb59eb174..945e35010 100644 --- a/website/docs/basics/autowiring.md +++ b/website/docs/basics/autowiring.md @@ -3,7 +3,7 @@ id: autowiring title: Autowiring --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) What is autowiring? diff --git a/website/docs/basics/backend.md b/website/docs/basics/backend.md index 08d197ee3..3b8697d79 100644 --- a/website/docs/basics/backend.md +++ b/website/docs/basics/backend.md @@ -3,7 +3,7 @@ id: backend title: General --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) In general, you can use anything as-is from the vendor library, or you can modify/add the functionality of existing classes by extending them in your project. diff --git a/website/docs/basics/basics-intro.md b/website/docs/basics/basics-intro.md index 26e544907..9761e4319 100644 --- a/website/docs/basics/basics-intro.md +++ b/website/docs/basics/basics-intro.md @@ -3,7 +3,8 @@ id: basics-intro title: Basics --- -Before WordPress 5.0 release, the themes were mostly PHP based on some JavaScript and CSS. Now it's a bit different because we have PHP in the core, JavaScript (specifically React.js) in the block editor, and some styles in the editor and the theme parts of the website. +Prior to WordPress 5.0, themes were mostly PHP-based, with JavaScript used only to provide interactive functionality on the website. +Now it's a bit different because we have PHP in the core, JavaScript (specifically React.js) in the block editor, and some styles in the editor and the theme parts of the website. Now that everything is different, we must adapt to the changes as well. diff --git a/website/docs/basics/block-manifest.md b/website/docs/basics/block-manifest.md index 56f53c586..c4dc1d9fe 100644 --- a/website/docs/basics/block-manifest.md +++ b/website/docs/basics/block-manifest.md @@ -3,7 +3,7 @@ id: block-manifest title: Block Manifest --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) This file contains all the configuration required for a block to work. It's used in WordPress [`registerBlockType`](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/) method to register a block. Using `manifest.json`, we can provide a configuration in JavaScript and PHP part of the block in one file. diff --git a/website/docs/basics/block-structure.md b/website/docs/basics/block-structure.md index 78f8fb932..21efe6ac5 100644 --- a/website/docs/basics/block-structure.md +++ b/website/docs/basics/block-structure.md @@ -3,7 +3,7 @@ id: block-structure title: Block Structure --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Your custom blocks are placed in the `src/Blocks/custom` folder. diff --git a/website/docs/basics/blocks-attributes.md b/website/docs/basics/blocks-attributes.md index 376eab455..e1801fa1b 100644 --- a/website/docs/basics/blocks-attributes.md +++ b/website/docs/basics/blocks-attributes.md @@ -3,7 +3,7 @@ id: blocks-attributes title: Attributes --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) If you were to reference the native [WordPress documentation](https://developer.wordpress.org/block-editor/developers/block-api/block-attributes/) about attributes in blocks, you can see that they support different types of attributes. In this chapter, we want to point out that you should avoid using objects for your attributes. diff --git a/website/docs/basics/blocks-component-in-block.md b/website/docs/basics/blocks-component-in-block.md index 707dc1232..e657c0a31 100644 --- a/website/docs/basics/blocks-component-in-block.md +++ b/website/docs/basics/blocks-component-in-block.md @@ -3,7 +3,7 @@ id: blocks-component-in-block title: Component in a Block --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Blocks and components work perfectly together because they are made that way. We simplified this as much as possible but there always a few things you need to do manually. diff --git a/website/docs/basics/blocks-component-manifest.md b/website/docs/basics/blocks-component-manifest.md index 03d7bf6e5..9e9e1ac0c 100644 --- a/website/docs/basics/blocks-component-manifest.md +++ b/website/docs/basics/blocks-component-manifest.md @@ -3,7 +3,7 @@ id: blocks-component-manifest title: Component Manifest --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) A component manifest is a bit different than the block manifest. The main difference is that the component manifest is a fully custom feature, and it is only here to provide a way to store configuration data and share it with multiple files in your project. diff --git a/website/docs/basics/blocks-component-structure.md b/website/docs/basics/blocks-component-structure.md index ff30aa155..569b90dd9 100644 --- a/website/docs/basics/blocks-component-structure.md +++ b/website/docs/basics/blocks-component-structure.md @@ -3,7 +3,7 @@ id: blocks-component-structure title: Component Structure --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Your custom components are placed in the `src/Blocks/components` folder. diff --git a/website/docs/basics/blocks-faq.md b/website/docs/basics/blocks-faq.md index 32f1cc615..2bf2f6738 100644 --- a/website/docs/basics/blocks-faq.md +++ b/website/docs/basics/blocks-faq.md @@ -3,7 +3,7 @@ id: blocks-faq title: Faq --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Before we dive into blocks and see how everything is set, we should describe this setup's mindset. If you've managed to set up your project by this point with the [WP-CLI](wp-cli) command `setup_theme`, you might have a few questions. We will try to answer all those questions here. diff --git a/website/docs/basics/blocks-global-manifest.md b/website/docs/basics/blocks-global-manifest.md index 9f75cadfe..e0996ad3f 100644 --- a/website/docs/basics/blocks-global-manifest.md +++ b/website/docs/basics/blocks-global-manifest.md @@ -3,7 +3,7 @@ id: blocks-global-manifest title: Global Manifest --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Global manifest is used to provide all the global configuration to the blocks and components, and much more. diff --git a/website/docs/basics/blocks-hooks.md b/website/docs/basics/blocks-hooks.md index fd3e950bc..c751a8917 100644 --- a/website/docs/basics/blocks-hooks.md +++ b/website/docs/basics/blocks-hooks.md @@ -3,7 +3,7 @@ id: blocks-hooks title: Hooks --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) WordPress block editor hooks provide the same functionalities as PHP hooks. They are used to modify the behavior of the existing blocks. diff --git a/website/docs/basics/blocks-important.md b/website/docs/basics/blocks-important.md index 84be88a66..0fca302d8 100644 --- a/website/docs/basics/blocks-important.md +++ b/website/docs/basics/blocks-important.md @@ -3,7 +3,7 @@ id: blocks-important title: Important --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Before you start developing and changing anything on your block/components, you should keep in mind how we have managed to create this setup and some of the side effects of automatic file loading. diff --git a/website/docs/basics/blocks-patterns.md b/website/docs/basics/blocks-patterns.md index d1fff9dfa..f629e52b2 100644 --- a/website/docs/basics/blocks-patterns.md +++ b/website/docs/basics/blocks-patterns.md @@ -3,7 +3,7 @@ id: blocks-patterns title: Patterns --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Block Patterns are predefined block layouts, ready to insert and tweak. diff --git a/website/docs/basics/blocks-registration.md b/website/docs/basics/blocks-registration.md index 64825541f..15b9a62f4 100644 --- a/website/docs/basics/blocks-registration.md +++ b/website/docs/basics/blocks-registration.md @@ -3,7 +3,7 @@ id: blocks-registration title: Registration --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Our setup works if you follow our naming convention and strict folder structure for all blocks, components, variations, patterns, and wrapper. diff --git a/website/docs/basics/blocks-reusable.md b/website/docs/basics/blocks-reusable.md index e39d8a28d..76e01ae58 100644 --- a/website/docs/basics/blocks-reusable.md +++ b/website/docs/basics/blocks-reusable.md @@ -3,7 +3,7 @@ id: blocks-reusable title: Reusable Blocks --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Block editor provides us with the reusable blocks out of the box. These blocks are a custom post type that holds blocks that you can call in your editor to reuse in multiple places. So if you change your reusable block that change will impact all places where this block is imported. diff --git a/website/docs/basics/blocks-special-use-cases.md b/website/docs/basics/blocks-special-use-cases.md index 3b6562900..56252db12 100644 --- a/website/docs/basics/blocks-special-use-cases.md +++ b/website/docs/basics/blocks-special-use-cases.md @@ -3,7 +3,7 @@ id: blocks-special-use-cases title: Special Use Cases --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) In our clients' projects, we noticed that sometimes you need to provide something special to your blocks, like changing the block editor block DOM structure or the attributes added inside the inner blocks. diff --git a/website/docs/basics/blocks-storybook.md b/website/docs/basics/blocks-storybook.md index 7c62f65ea..54eafeb95 100644 --- a/website/docs/basics/blocks-storybook.md +++ b/website/docs/basics/blocks-storybook.md @@ -3,7 +3,7 @@ id: blocks-storybook title: Storybook --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) We have created a full storybook that hosts all our blocks/components/variations with a fully functional block editor, where you can try out how blocks work and behave. diff --git a/website/docs/basics/blocks-structure.md b/website/docs/basics/blocks-structure.md index 7366294af..bf1cbb79a 100644 --- a/website/docs/basics/blocks-structure.md +++ b/website/docs/basics/blocks-structure.md @@ -3,7 +3,7 @@ id: blocks-structure title: Structure --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) For the library to work and register blocks dynamically, a specific folder structure and naming must be followed. diff --git a/website/docs/basics/blocks-styles.md b/website/docs/basics/blocks-styles.md index 87d36d244..948e565af 100644 --- a/website/docs/basics/blocks-styles.md +++ b/website/docs/basics/blocks-styles.md @@ -3,7 +3,7 @@ id: blocks-styles title: Styles --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) We decided to remove all support for IE 11. That decision opened up doors that lead to new, awesome features and all the cool stuff. One of those features is CSS variables with block manifest and global settings. diff --git a/website/docs/basics/blocks-transforms.md b/website/docs/basics/blocks-transforms.md index d60afa95a..57302a6f8 100644 --- a/website/docs/basics/blocks-transforms.md +++ b/website/docs/basics/blocks-transforms.md @@ -3,7 +3,7 @@ id: blocks-transforms title: Transforms --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Block Transforms is an API that allows a block to be transformed from and to other blocks, as well as from other entities. diff --git a/website/docs/basics/blocks-variations.md b/website/docs/basics/blocks-variations.md index 2b01a1c74..d019e8958 100644 --- a/website/docs/basics/blocks-variations.md +++ b/website/docs/basics/blocks-variations.md @@ -3,7 +3,7 @@ id: blocks-variations title: Variations --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Block variations allow developers to define instances of existing blocks by changing their default values. diff --git a/website/docs/basics/blocks-wrapper.md b/website/docs/basics/blocks-wrapper.md index 5c249f858..a88c1c0d2 100644 --- a/website/docs/basics/blocks-wrapper.md +++ b/website/docs/basics/blocks-wrapper.md @@ -3,7 +3,7 @@ id: blocks-wrapper title: Wrapper --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) The wrapper is our best and most powerful feature. In a nutshell, the wrapper is nothing more than a high order component (parent component). diff --git a/website/docs/basics/blocks.md b/website/docs/basics/blocks.md index 66a68cb97..36498acbc 100644 --- a/website/docs/basics/blocks.md +++ b/website/docs/basics/blocks.md @@ -3,7 +3,7 @@ id: blocks title: Blocks --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) Since WordPress 5.0, we were introduced to the new editing experience using the so-called Gutenberg blocks. With blocks, the idea is to have the same look and feel in the editor as on the front end. As a developer, you just got a new technology that you should know if you want to build a great project on WordPress. That new technology is React because everything regarding blocks is done using React. diff --git a/website/docs/basics/browser-sync.md b/website/docs/basics/browser-sync.md index 24a605cdd..58f247e17 100644 --- a/website/docs/basics/browser-sync.md +++ b/website/docs/basics/browser-sync.md @@ -1,16 +1,16 @@ --- id: browser-sync -title: Browser Sync +title: Browsersync --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) [Browsersync](https://browsersync.io/docs) is a Node module that enables you to develop sites faster. It will react to any code change and 'refresh' the site without you needing to refresh it. In the background, it runs a small local server. When configured, it will inject a script on your web page to react to any code change. Besides that, you can test your site on various devices on the same network. -If comes with the boilerplate by default. When you run: +It's part of the Eightshift Development Kit by default. When you run: ```bash npm start @@ -34,7 +34,7 @@ Using the IP address, you can open it on any device (mobile phone or tablet) tha ## Using SSL for local development -By default BrowserSync does not work with https urls but if you use HTTPS in your local environment you can simply provide additional key to the Webpack config to make it work. +By default, BrowserSync does not work with HTTPS URLs. If you use HTTPS in your local environment you can simply provide an additional key in the Webpack config to make it work. ```js module.exports = (env, argv) => { diff --git a/website/docs/basics/dynamic-import.md b/website/docs/basics/dynamic-import.md index e39bf673a..547218bfb 100644 --- a/website/docs/basics/dynamic-import.md +++ b/website/docs/basics/dynamic-import.md @@ -3,35 +3,35 @@ id: dynamic-import title: Dynamic Import --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) -When writing all our JavaScript code we like to make it as fast and optimized as possible and there is no better way of doing that other than utilizing one powerful tool from Webpack called [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports). +As JavaScript code runs on the visitor's device, it's crucial that it's as fast and optimized as possible. A powerful tool from Webpack called [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports) helps with that. -This method provides us the ability to write all our JavaScript code but load them in the DOM only when it is used, basically, this is what all JavaScript libraries use out of the box. +Dynamic imports provide us the ability to load our JavaScript code only when it's used. -By writing all our JavaScript code like this we can: -* optimize loading time. -* reduce the size of finished bundled JavaScript code. -* have websites that are fast and this can positively impact your Seo rating. +By writing all JavaScript code using dynamic imports, we can reap significant benefits: +* optimize loading time +* reduce the size of finished bundled JavaScript code +* have websites that are fast, which can positively impact your SEO rating ## How does it work? -In a nutshell, you load all your code using JavaScript promises and Webpack splits all these promises into separate file chinks. Once the condition to resolve the promise is set (generally we check if the selector is present in the DOM), Webpack automatically injects your chunk in the DOM and loads it up. This is why you will see in your public folder a bunch of smaller files called (`0.js`, `1.js`, `2.js`, etc). +In a nutshell, you load all your code using JavaScript promises. Webpack splits all these promises into separate file chunks. Once the condition to resolve the promise is set (generally, if a selector is present in the DOM), Webpack automatically injects your chunk in the DOM and loads it up. This is why you will see a bunch of smaller files (`0.js`, `1.js`, `2.js`, etc) in your public folder instead of a single large file. You don't need to think about this. Webpack just does it for you. ## Example -For example, let's make a carousel. We like to write all our JavaScript code in classes so we will provide an example for that but you can use this with functions as well. +For example, let's make a carousel. An Eightshift convention is to write JavaScript code using classes, so we'll provide an example for that. However, you can use this approach with functions as well. -**We have to files:** +**We have two files:** * **index.js** - the main entry point for your JavaScript feature. * **className.js** - class with your JavaScript features that you can reuse. ### index.js -This is a version where you have multiple instances of this feature on one page. If you are creating a feature for your block/component you will use the following example. +This is a version where you have multiple instances of a feature on one page. If you are creating a feature for your block/component, you'll use something along these lines. ```js import domReady from '@wordpress/dom-ready'; @@ -44,7 +44,7 @@ domReady(() => { const selector = `.${blockJsClass}`; const elements = document.querySelectorAll(selector); - // This is the important part because if this condition is true this promise will resolve and your chink will be loaded in the DOM. + // This is the important part - if this condition is true, this promise will resolve and your chunk will be loaded in the DOM. if (!elements.length) { return; } @@ -66,7 +66,7 @@ domReady(() => { }); ``` -If you are sure you will have only one instance of this feature on one-page use the following code in your `index.js` file. +If you are sure you will have only one instance of this feature on one-page, you can use the following code in your `index.js` file. ```js import domReady from '@wordpress/dom-ready'; diff --git a/website/docs/basics/example-class.md b/website/docs/basics/example-class.md index 1035f1c86..9c203049c 100644 --- a/website/docs/basics/example-class.md +++ b/website/docs/basics/example-class.md @@ -3,7 +3,7 @@ id: example-class title: Example Class --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) As you've already seen in the [WP-CLI](wp-cli) chapter, we have many finished features prepared for you. However, we want to make things even easier for you, so we created an example service class for you to use. diff --git a/website/docs/basics/extending-classes.md b/website/docs/basics/extending-classes.md index e038ce7d5..7bd9458af 100644 --- a/website/docs/basics/extending-classes.md +++ b/website/docs/basics/extending-classes.md @@ -3,7 +3,7 @@ id: extending-classes title: Extending Classes --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) You can extend every class from the library. To follow the good practice, you should never use the class directly from the Eightshift-libs in your service container (except from helpers and traits). Instead, you should create a class in your project and extend the class from the Eightshift-libs. That is why we made all those [WP-CLI](wp-cli) commands you saw in the previous chapter. diff --git a/website/docs/basics/fonts.md b/website/docs/basics/fonts.md index 361dd2b6e..2019d462a 100644 --- a/website/docs/basics/fonts.md +++ b/website/docs/basics/fonts.md @@ -3,10 +3,10 @@ id: fonts title: Fonts --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) Fonts can be added to your project in multiple ways, depending on your project's needs. In general, if you can use fonts from an external source like Google Fonts, use that approach because the fonts are loaded smartly. On the other hand, if you have fonts that are added to your project, below are the steps to follow to make them available in the project. * Put your font files in this folder: `assets/fonts`. -* Import each file in the `assets/fonts/index.js` so that the Webpack knows how to process these files in its build process. +* Import each file in the `assets/fonts/index.js` so that Webpack knows how to process these files in its build process. * In your project, load the font family using font-face [method](/eightshift-docs/sass). We recommend that you create a new file `assets/styles/parts/utils/_defaults.scss` and put everything in that file. diff --git a/website/docs/basics/frontend.md b/website/docs/basics/frontend.md index 07b3e2365..8d284d4cc 100644 --- a/website/docs/basics/frontend.md +++ b/website/docs/basics/frontend.md @@ -3,7 +3,7 @@ id: frontend title: General --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) In general, you can use anything as-is from the `node_modules` library, or you can modify/add the functionality in your project. diff --git a/website/docs/basics/global-settings.md b/website/docs/basics/global-settings.md index e8b79bde4..b26236288 100644 --- a/website/docs/basics/global-settings.md +++ b/website/docs/basics/global-settings.md @@ -3,7 +3,7 @@ id: global-settings title: Global Settings --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) > This chapter is only relevant in setups that don't use CSS variables. If you are using CSS variables please skip to the [Blocks Styles chapter](blocks-styles) chapter. diff --git a/website/docs/basics/helpers-javascript.md b/website/docs/basics/helpers-javascript.md index 57b8aa7da..44b9b662d 100644 --- a/website/docs/basics/helpers-javascript.md +++ b/website/docs/basics/helpers-javascript.md @@ -3,7 +3,7 @@ id: helpers-javascript title: JavaScript --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) All JavaScript helpers can be imported from the `@eightshift/frontend-libs/scripts` folder, so you don't need to think about the internal folder structure of Eightshift Frontend Libs. If you want multiple functions imported just concatenate them in the import like this: diff --git a/website/docs/basics/helpers-php.md b/website/docs/basics/helpers-php.md index 1978bba0c..7b433eb11 100644 --- a/website/docs/basics/helpers-php.md +++ b/website/docs/basics/helpers-php.md @@ -3,7 +3,7 @@ id: helpers-php title: PHP --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) ## ensureString diff --git a/website/docs/basics/helpers-scss.md b/website/docs/basics/helpers-scss.md index 4914bb7cf..14c354ea3 100644 --- a/website/docs/basics/helpers-scss.md +++ b/website/docs/basics/helpers-scss.md @@ -3,7 +3,7 @@ id: helpers-scss title: Scss --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) For years, we have collected a list of useful SASS mixins, placeholders, and functions you can use in a project. You don't need to have all of this in your project. Check out our documentation and see what we have in store for you. diff --git a/website/docs/basics/library.md b/website/docs/basics/library.md index cc7b76593..e82e9e255 100644 --- a/website/docs/basics/library.md +++ b/website/docs/basics/library.md @@ -1,12 +1,13 @@ --- id: library -title: Library +title: SCSS Library --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +Eightshift Frontend Libs contains a collection of useful SCSS mixins, functions and helpers you can use in projects. -For years, we have collected a list of useful SASS mixins, functions, and other stuff you can use in a project. At one point, we felt stupid for copy/pasting code across multiple projects, so we created Eightshift Frontend Libs. This library allows you to use whatever we offer without all that unnecessary clutter. +For years, we have collected a list of them. At one point, we felt it was ineffective to copy-paste code across multiple projects, so we created Eightshift Frontend Libs. This allows you to use whatever we offer without all that unnecessary clutter. Check out our documentation and import what you need from Eightshift Frontend Libs. @@ -14,10 +15,10 @@ Check out our documentation and import what you need from Eightshift Frontend Li ## How to use it -Sass mixing, functions, and helpers are located in Eightshift Frontend Libs. Therefore, if you are using our Webpack build, you are all set. You can use it by importing it into your project like this: +SCSS mixins, functions, and helpers are located in Eightshift Frontend Libs. Therefore, if you are using our Webpack build, you are all set. You can use it by importing it into your project like this: ```scss @import '@eightshift/frontend-libs/styles/index.scss'; ``` -But if you used our `wp boilerplate setup_theme` command, you are all set. Eightshift Frontend Libs are injected in the `_shared.scss` file in your project. +However, if you used our `wp boilerplate setup_theme` command, you are all set. Eightshift Frontend Libs are injected in the `_shared.scss` file in your project. diff --git a/website/docs/basics/manifest.md b/website/docs/basics/manifest.md index 5c0c8a84c..72a4d8a59 100644 --- a/website/docs/basics/manifest.md +++ b/website/docs/basics/manifest.md @@ -1,13 +1,15 @@ --- id: manifest -title: Manifest +title: Assets Manifest --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) -In the build process, Webpack creates all the static files from your assets folder and also `manifest.json` inside the public folder. The manifest file contains a key/value list that we use to call the location of the assets dynamically. +> This `manifest.json` file is generated by Webpack, and is different from the rest of Eightshift manifests described elsewhere in the documentation. -This class provides `manifest.json` file location and helpers to return the full path for a specific asset. +In the build process, Webpack creates all the static files from your assets folder and a `manifest.json` file inside the public folder. The manifest file contains a list of key/value pairs that we use to set the location of the assets dynamically. + +This class provides the location of the `manifest.json` file and helpers to return the full path for a specific asset. ## How to use it @@ -15,7 +17,7 @@ First, install the manifest class using this command: `wp boilerplate create_manifest` -You will see a custom filter you can use to fetch the item from the public folder in your class. This is the custom filter: +You will see a custom filter you can use to fetch an item from the public folder in your class. This is the custom filter: ```php /** @@ -36,7 +38,7 @@ public function register(): void } ``` -To use this filter, add the following code and provide the correct name of your asset: +To use this filter to fetch asset URLs, add the following code and provide the correct name of your asset: ```php use CoolProject\Manifest\Manifest; @@ -52,12 +54,12 @@ If there is no `manifest.json` file or you provided the wrong asset name, there ## Why not just fetch the asset the old-fashioned way? -By the old-fashioned way, we mean running something like this: +By the old-fashioned way, we mean doing something like this: ```php $logo = get_template_directory_uri() . 'public/logo.svg'; ``` -You can definitely do this. But with our filter, if you want to change the public folder location or public folder name for some reason, you can change it in one place and you're done. +You can definitely do this. However, using the manifest approach, if you want to change the public folder location or public folder name for some reason, you can change it in one place and you're done. -If you are using the old-fashioned way, you would need to search and replace the whole project and implement the change. There is always a chance you would miss something, break the project, etc. +If you are using the old-fashioned way, you would need to search and replace the whole project and implement the change. There is always a chance you will miss something and somehow break the project. diff --git a/website/docs/basics/namespaces.md b/website/docs/basics/namespaces.md index 71724fb74..2bd360e59 100644 --- a/website/docs/basics/namespaces.md +++ b/website/docs/basics/namespaces.md @@ -3,15 +3,17 @@ id: namespaces title: Namespaces --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) -> PHP part of this project lives in `EightshiftLibs` namespace. +> The PHP codebase of this project lives in `EightshiftLibs` namespace. -Because WordPress lives in a global namespace, we had to provide the way for your project to be unique. That is why we implemented [**Imposter**](https://github.com/infinum/imposter-plugin) script inside `composer.json`. Imposter adds a namespace prefix on all the packages inside the `vendor` folder that uses namespacing. +Because WordPress lives in a global namespace, we had to provide the way for your project to be unique. That is why we implemented [**Imposter**](https://github.com/infinum/imposter-plugin) in `composer.json`. Imposter adds a namespace prefix to all the packages inside the `vendor` folder that use namespacing. -You can change the vendor prefix in your `composer.json` file. But if you do this, make sure you delete the `vendor` folder before running the command to install the composer packages again with the `composer install` command. +You can change the vendor prefix in your `composer.json` file. If you do this, make sure you delete the `vendor` folder and re-run `composer install`. +Using the default setup, your project will have the namespace you defined in the setup process. +However, let's say you change your `composer.json` file to contain this snippet: ```json "autoload": { "psr-4": { @@ -25,14 +27,16 @@ You can change the vendor prefix in your `composer.json` file. But if you do thi } ``` -For example, with the default setup, your project will have the namespace you defined in the setup process. But let's say you have the structure from the previous example: - - Your current namespace is: `CustomProject`. -- Namespace for all packages used from Eightshift libs is `EightshiftBoilerplateVendor\CustomProject`. -- Also, every package you additionally install will follow the same convention: `EightshiftBoilerplateVendor\SomePackageNamespace`. +- Namespace for Eightshift Libs becomes: `EightshiftBoilerplateVendor\EightshiftLibs`. +- Every package you additionally install will follow the same convention: `EightshiftBoilerplateVendor\SomePackageNamespace`. -**To sum it up**: you don't need to change the default vendor prefix if you only run one theme or one plugin with Eightshift Boilerplate. But if you have multiple Eightshift Boilerplate powered themes or plugins installed, please change the vendor prefix on each of the projects. +**To sum it up**: you don't need to change the default vendor prefix if you only run one theme or one plugin with Eightshift Development Kit. If you have multiple Eightshift Development Kit-powered themes or plugins installed, please change the vendor prefix on each of the projects. ### Important note -If you are installing additional composer packages make sure that they don't have any inline namespace usage. All `use` keys must be defined in the top of the files. Imposter plugin is not able to resolve this and it will throw and fatal error. To fix this ether create a PR on the package and fix this for everyone, or you can exclude this package from imposter script. Keep in mind that can have some unexpected side effects that we can't predict. +If you are installing additional composer packages, make sure that they don't have any inline namespace usage. All referenced classes should be imported with `use` statements, which must be defined at the top of files. + +The Imposter plugin is not able to replace inline namespaces, which will cause issues with classname resolution and result in a fatal error getting thrown. + +To fix these issues, either create a PR on the package and fix this for everyone, or exclude this package from imposter script. Keep in mind that can have some unexpected side effects that we can't predict. diff --git a/website/docs/basics/rest-field.md b/website/docs/basics/rest-field.md index 0fc912d7a..c00884dc5 100644 --- a/website/docs/basics/rest-field.md +++ b/website/docs/basics/rest-field.md @@ -1,13 +1,13 @@ --- id: rest-field -title: Rest Field +title: REST Field --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) -This class is used to update the existing Rest API Field or provide a new field to the existing Rest API. +This class is used to update an existing REST API Field or provide a new field to the existing REST API. -To create a new class for extending the Rest API field, run this command: +To create a new class for extending an REST API field, run this command: `wp boilerplate create_rest_field` diff --git a/website/docs/basics/rest-route.md b/website/docs/basics/rest-route.md index ed8f00a71..dcfa14fab 100644 --- a/website/docs/basics/rest-route.md +++ b/website/docs/basics/rest-route.md @@ -1,13 +1,13 @@ --- id: rest-route -title: Rest Route +title: REST Route --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) -This class is used to create a new Rest API route. +This class is used to create a new REST API route. -To create a new class for the Rest API route, run this command: +To create a new class for the REST API route, run this command: `wp boilerplate create_rest_route` diff --git a/website/docs/basics/rest.md b/website/docs/basics/rest.md index fe7d717db..ab6ddafe1 100644 --- a/website/docs/basics/rest.md +++ b/website/docs/basics/rest.md @@ -1,41 +1,41 @@ --- id: rest -title: Rest Intro +title: REST Intro --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) -Depending on the type of projects you are working on, you might need to create a new REST API route or add a new API field to the existing route. +Depending on the type of projects you are working on, you might need to create a new REST API route or add a new API field to an existing route. We have prepared four interfaces and two abstract classes for you. -In general, you will use only what you need from the provided options. +In general, you will only use what you need from the provided options. ### CallableFieldInterface.php -The interface used in Rest API Field for providing callback method. +The interface used in REST API Fields for providing a callback method. ### CallableRouteInterface.php -The interface used in Rest API Route for providing callback method. +The interface used in REST API Routes for providing a callback method. ### RouteSecurityInterface.php -The interface used in Rest API Route for providing authentication methods. +The interface used in REST API Routes for providing authentication methods. ### RouteInterface.php -The interface used in Rest API Route for providing general options for your route like variables for `READABLE`, `CREATABLE`, etc... +The interface used in REST API Routes for providing general options for your route, such as variables for `READABLE`, `CREATABLE`, etc... ### AbstractField.php -Abstract class used in Rest API Field for updating existing fields or providing a new field to the existing Rest API. +Abstract class used in REST API Field for updating existing fields or providing a new field to the existing REST API. Please check the implementation details in [this example](rest-field). ### AbstractRoute.php -Abstract class used in Rest API Route for adding a new Rest API route. +Abstract class used in REST API Route for adding a new REST API route. Please check the implementation details in [this example](rest-route). diff --git a/website/docs/basics/the-structure.md b/website/docs/basics/the-structure.md deleted file mode 100644 index 6f2016e25..000000000 --- a/website/docs/basics/the-structure.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -id: the-structure -title: The Structure ---- - -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) - -If you've followed the chapters this far and have set your first project with all the classes from the `wp boilerplate setup_theme` command, you saw that you have an `src` folder in the root of your project. - -In that root folder, you have a bunch of folders with classes. We like to structure our projects by features, so for example, all `custom post type` registrations will be located in the `CustomPostType` folder. - -Using the [WP-CLI](wp-cli) commands, you follow our folder structure so that all of your projects will have the same layout. This helps us with onboarding new developers to the project. They can know where things are from the start. - -Here is a small tip from us: **"Organize your projects by functionality"**. - -## The structure - -As we already mentioned, try to be consistent and organized with your project. Here is the structure list generated by the libs. We will explain to you why and how we use all of these files: - -- src - - Blocks - - Columns - - Config - - CustomMeta - - CustomPostType - - CustomTaxonomy - - Enqueue - - Admin - - Blocks - - Theme - - Exception - - Helpers - - I18n - - Login - - Main - - Manifest - - Media - - Menu - - ModifyAdminAppearance - - Plugin - - Rest - - ThemeOptions - - View -- .storybook -- .gitignore -- .eslintignore -- .eslintrc -- .stylelintrc -- babel.config.js -- composer.json -- composer.lock -- package-lock.json -- package.json -- phpcs.xml.dist -- postcss.config.js -- README.md -- webpack.config.js - -### Blocks - -Blocks are used, as the name implies, for the block editor. You can read about blocks in more detail in [Blocks chapter](blocks). - -### Columns - -This class contains all the custom admin listing columns hooks for your project, like post type, taxonomy and user lists. - -### Config - -This class is used to define all the configuration methods for your project like `project name`, `project version`, `rest routes namespace`, and much more. - -You can define your project's needs in this class as a static method that you can quickly use. - -### CustomMeta - -This class contains all the custom meta hooks for your project. - -### CustomPostType - -This class contains all the custom post type hooks for your project. We created a preset for you, so this class looks the same on all the projects. - -### CustomTaxonomy - -This class contains all the custom taxonomy hooks for your project. Like custom post type, we created a preset for you, so this class looks the same on all the projects. - -### Enqueue - -These classes will handle JavaScript and CSS files for your project, depending on the location you want to use it: -- **Admin** - Used in the admin (not block editor) part of your project. You can find the files inside the `assets` folder with the `-admin` suffix. -- **Blocks** - Used in the block editor part of your project. You can find the files inside the `src/Blocks/assets` folder. As blocks are complicated, we have files loaded only in the admin-editor part of the project, those files have an `-editor` suffix. The rest of the files with no suffix load on the admin-editor part and the project's front end. -- **Theme** - Used in the theme (frontend) part of your project. You can find the files inside the `assets` folder with no suffix. You would use these files for stuff related to your project that is not associated with components and blocks. (To be honest, we barely use these files.) - -The usage of any of these classes is optional, and you can use only what you need. Eightshift Boilerplate `setup_theme` command comes with all three classes already implemented. Keep in mind that enqueue classes work in combination with the Webpack build of your project. - -We named all our files with `application` in prefix. If you don't like the name, you can change it by providing the project overrides for constants used in the Eightshift-Libs. If you change the file names, you must make changes to the Webpack build process as well. For modifying the Webpack part you can check in the [Webpack chapter](webpack). - -### Exception - -This class is used to store every exception that can be thrown from the project. - -### Helpers - -All our helpers are stored here and in general, you can directly use these classes without extending them. But if you want to extend the functionality of our helpers you can put them in this folder. - -### I18n - -This class is used to define all hooks related to the languages and translations for your project. - -### Login - -We use this file to change the logo link on the login page, but you can use it however you seem fit. - -### Main - -This is the main entry point file for all your classes. It implements DI container and autowiring with the main action that loads everything in your project inside the WordPress ecosystem. You can provide manual service classes here as well. We covered this in the [autowiring chapter](autowiring). - -### Manifest - -This class provides `manifest.json` file location and helpers to return the full path for a specific asset. We will cover this in more detail in the [manifest chapter](manifest). - -### Media - -This class is used to add all custom project implementation for media like adding custom image size, enabling SVG image, etc. - -### Menu - -This class is used to register menu positions. - -### ModifyAdminAppearance - -This class is used to change admin appearance. We use it to change the admin color palette depending on the environment. - -### Plugin - -This class is used only in the Eightshift boilerplate plugin and it holds files required for activation and deactivation of the plugin. - -### Rest - -These classes will handle the rest fields and routes for your project. We will cover this in more detail in the [rest chapter](rest). - -### ThemeOptions - -This class is used to add admin menu options and configurations for theme options and settings. - -### View - -This class is used to add filters used in escaping unsafe tags in the `wp_kses_post` and `wp_kses` methods. - -### .storybook - -This folder contains all of the files necessary to run the storybook in your project. Read more about it on [this link](https://storybook.js.org/). - -### .gitignore - -As the name implies, this file is used to provide restrictions for files that will not be added to the git structure. Read more about it on [this link](https://git-scm.com/). - -### .eslintignore - -This file provides similar restrictions but this time for files/folders that will not be checked with the eslint. - -### .eslintrc - -This file provides all the definitions used for linting JavaScript files. Read more about it on [this link](https://eslint.org/). - -### .stylelintrc - -This file provides all the definitions used for linting Style (SCSS/CSS) files. Read more about it on [this link](https://stylelint.io/). - -### babel.config.js - -This file provides all the definitions of how your JavaScript code will be compiled, what standard you will use, and much more. Read more about it on [this link](https://babeljs.io/). - -### composer.json - -This file contains all the vendor packages you are using in your project. They are added to your project using the `composer install` command. Read more about it on [this link](https://getcomposer.org/). - -### composer.lock - -Lock files are used to set the package version to the exact release. This ensures that everyone gets the same package version when doing the installation. - -### package-lock.json - -The same as `composer.lock` but for node_modules. - -### package.json - -This file contains all the node_modules packages you are using in your project. They are added to your project using the `npm install` command. Read more about it on [this link](https://nodejs.dev/). - -### phpcs.xml.dist - -This file provides all the definitions used for linting PHP files. Read more about it on [this link](https://github.com/squizlabs/PHP_CodeSniffer). - -### postcss.config.js - -Postcss works in correlation with Webpack, and it defines what additional plugins you are going to use when building your css files. Read more about it on [this link](https://postcss.org/). - -### README.md - -Readme is always good to have. You should always define here how to set up a new project and make project switching a breeze. - -### webpack.config.js - -This file provides all the definitions used for building your JavaScript and CSS files. We will cover this in more detail in the [Webpack chapter](webpack). diff --git a/website/docs/basics/webpack.md b/website/docs/basics/webpack.md index edca3b48a..bbe8dc1c4 100644 --- a/website/docs/basics/webpack.md +++ b/website/docs/basics/webpack.md @@ -3,20 +3,20 @@ id: webpack title: Webpack --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) -At its core, Webpack is a static module bundler for modern JavaScript applications. When Webpack processes your application, it internally builds a dependency graph that maps every module your project needs and generates one or more bundles. Learn more about Webpack [here](https://webpack.js.org/concepts/). +At its core, Webpack is a static module bundler for modern JavaScript applications. When Webpack processes your application, it builds an internal dependency graph that maps every module your project needs and generates one or more bundles. [Learn more about Webpack](https://webpack.js.org/concepts/). To put it simply, Webpack takes your development files and creates a production-ready version of them based on the config. -Eightshift Boilerplate comes with everything set for you to use out of the box. In the root of your project, you will find a file called `webpack.config.js`. If you open it, you will see that the configuration is pulled from the Eightshift Frontend Libs library. +Eightshift Development Kit comes with everything set up out of the box. In the root of your project, you will find a file called `webpack.config.js`. If you open it, you will see that the configuration is pulled from the Eightshift Frontend Libs library. You can remove this config and write everything from scratch (keep in mind that this is a lot of work), or you can use our config and extend/remove whatever you need. ## Override built-in functionality To remove built-in functionality, add a new array to the config called `overrides`. -If you provide any of the `overrides keys`, it will remove that config from the feature from the build. +If you provide any of the `overrides` keys, it will remove that config from the feature from the build. You can't change our config; you can only remove it and make your own. @@ -59,7 +59,7 @@ const projectConfig = { } ``` -## Add a new custom functionality +## Add new custom functionality Let's say you want to add a custom `html-webpack-plugin` to the build. You can simply use all the native [webpack features](https://webpack.js.org/guides/), like in this example: diff --git a/website/docs/basics/wp-cli.md b/website/docs/basics/wp-cli.md index 9d775c4b9..55d230e3b 100644 --- a/website/docs/basics/wp-cli.md +++ b/website/docs/basics/wp-cli.md @@ -3,13 +3,13 @@ id: wp-cli title: WP-CLI --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) -We have already mentioned the WP-CLI feature of Eightshift Boilerplate. Now, let's dig a little deeper into this awesome feature. We took our time to set up a bunch of WP-CLI commands that will help you set everything up and use all our features without worrying about correct names, files, and organization. +Eightshift Development Kit provides extensive [WP-CLI](https://wp-cli.org/) tooling, allowing you to automate bootstrapping of common code, adding blocks from the Frontend Libs library to your projects and more using `wp boilerplate`. ## How it works -In your project's entry point, you have something like this: +In your project's entry point (usually `functions.php`), you'll find something along these lines: ```php /** @@ -20,13 +20,13 @@ if (class_exists(Cli::class)) { } ``` -This code loads WP-CLI class from Eightshift Libs responsible for registering all of our custom commands. Keep in mind that, since WP-CLI code loads inside the theme/plugin, that same theme/plugin **must** be activated in the WordPress admin. +This code loads the WP-CLI class from Eightshift Libs, which handles command registration for all of our commands. As this command registration is part of the theme/plugin code, this means that the same theme/plugin **must be activated** for `wp boilerplate` to work. To run the WP-CLI command and see what you can use, run this command in your terminal: `wp boilerplate --help` -> By default, your project's WP-CLI commands run under the parent name `boilerplate` defined in the upper code. +> By default, your project's WP-CLI commands run under the parent name `boilerplate`, as defined above. You can change that by simply replacing the string inside the load method like this: @@ -39,7 +39,7 @@ if (class_exists(Cli::class)) { } ``` -Now, your project's WP-CLI loads like this: +Now, your project's WP-CLI commands are available using: `wp superCoolTheme --help`. @@ -47,15 +47,14 @@ This is especially handy when you have multiple Eightshift Boilerplate powered t ## Options and commands -When you type each command in the terminal, it will do some action. Some commands will ask you for additional parameters. You can see them if you run the `command name` and `--help` like this: +To get to know which commands are available and what do they do, run `wp boilerplate --help`. +The `--help` argument is available on all of our commands and provides a description of the command and a list of required and optional parameters for the command. `wp boilerplate create_config --help` -Under the `OPTIONS`, you can see all required and optional parameters you can pass to the command to fine-tune your output. - ### Commands -We have defined a few command prefixes: +We use these common prefixes for commands: - **create** - services classes that will be copied to your project. - **init** - additional functions, methods and helpers that will be copied to your project. @@ -65,16 +64,16 @@ We have defined a few command prefixes: > **Make WP-CLI your best friend, and your coding life will be much more comfortable, trust us.** -We will explain some classes that we think are necessary in more detail in the next chapter. For the rest of the classes, you can find the descriptions by running `--help` after each command. +While we might go into more details about some of these commands, we won't be documenting all of them here - use the built-in manuals for more information about particular commands and to discover what's available. Don't gloss over them, as using `wp boilerplate` is a particularly useful tool when building projects with Eightshift Development Kit. ## Running commands in multisite -When you are running a multisite setup you must always provide the additional `--url` parameter because without that parameter WordPress will always run the code from the current primary domain set in the `wp-config.php`. +When you are running a multisite setup, you should always provide the additional `--url` parameter. Otherwise, WP-CLI will always run the command on the main site. -Here is an example for command running from the primary domain: +Here is an example for command running on the primary site: `wp boilerplate create_config` -and here is an example for command running in the sub site: +and here is an example for command running on the subsite: `wp boilerplate create_config --url='custom.domain.com'` diff --git a/website/docs/basics/writing-styles.md b/website/docs/basics/writing-styles.md index 9f0a9e4f6..60acf3d8b 100644 --- a/website/docs/basics/writing-styles.md +++ b/website/docs/basics/writing-styles.md @@ -3,7 +3,7 @@ id: writing-styles title: Writing Styles --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs) > This chapter is only relevant in setups that don't use CSS variables. If you are using CSS variables please skip to the [Blocks Styles chapter](blocks-styles) chapter. diff --git a/website/docs/eightshift-frontend-libs.md b/website/docs/eightshift-frontend-libs.md index 0d9373177..3988bcfb8 100644 --- a/website/docs/eightshift-frontend-libs.md +++ b/website/docs/eightshift-frontend-libs.md @@ -3,27 +3,26 @@ id: eightshift-frontend-libs title: Eightshift Frontend Libs --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) +[![docs-source](https://img.shields.io/badge/source-eightshift--frontend--libs-yellow?style=for-the-badge&logo=javascript&labelColor=2a2a2a)](https://github.com/infinum/eightshift-frontend-libs/tree/develop/blocks/init/src/blocks/) -This library is meant to bring the modern front-end development tools to the [Eightshift Boilerplate](https://github.com/infinum/eightshift-boilerplate) or [Eightshift Boilerplate Plugin](https://github.com/infinum/eightshift-boilerplate-plugin), but you can use it on any WordPress project. +This library is meant to bring modern front-end development tools to the [Eightshift Boilerplate](https://github.com/infinum/eightshift-boilerplate) or [Eightshift Boilerplate Plugin](https://github.com/infinum/eightshift-boilerplate-plugin), but you can use it on any WordPress project. ## Prerequisites The knowledge of the core editor components and React.js is recommended, since this library is focused on working with the new block editor and contains custom blocks. If you want to create your custom blocks, that knowledge will come in handy. -The library can be used for pure Webpack/JS/Scss functionality, but if you want to use our blocks, [Eightshift Libs](https://github.com/infinum/eightshift-libs/) must be used in tandem because they handle block registration, etc. +The library can be used for pure Webpack/JS/SCSS functionality, but if you want to use our blocks, [Eightshift Libs](https://github.com/infinum/eightshift-libs/) must be used in tandem because they handle block registration, attribute handling and more. ### The library contains: - All JS packages required for the Webpack build - ESLint ruleset -- StyleLint ruleset +- Stylelint ruleset - Babel ruleset - A collection of useful front-end utility modules - The complete storybook of over 30+ useful blocks and components -- Block editor block example -- Block editor blocks initial setup for the [Eightshift Boilerplate](https://github.com/infinum/eightshift-boilerplate) -- Some cool custom components for block editor +- Block editor block examples +- A growing collection of blocks and components - The complete Webpack build for [Eightshift Boilerplate](https://github.com/infinum/eightshift-boilerplate) - Helpers for creating dynamic block editor blocks - ... diff --git a/website/docs/eightshift-libs.md b/website/docs/eightshift-libs.md index 5ff36d6b5..ae698bb7f 100644 --- a/website/docs/eightshift-libs.md +++ b/website/docs/eightshift-libs.md @@ -3,7 +3,7 @@ id: eightshift-libs title: Eightshift Libs --- -[![docs-source](https://img.shields.io/badge/source-eigthshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) +[![docs-source](https://img.shields.io/badge/source-eightshift--libs-blue?style=for-the-badge&logo=php&labelColor=2a2a2a)](https://github.com/infinum/eightshift-libs) This library is aimed at bringing modern back-end development tools to the [Eightshift Boilerplate](https://github.com/infinum/eightshift-boilerplate) or [Eightshift Boilerplate Plugin](https://github.com/infinum/eightshift-boilerplate-plugin), but you can use it on any WordPress project. diff --git a/website/docs/theme.md b/website/docs/theme.md index aebb037f3..f75c5a6c7 100644 --- a/website/docs/theme.md +++ b/website/docs/theme.md @@ -22,14 +22,14 @@ All additional steps after the initial setup are done using WP_CLI commands, so ## Specify version to create -In order to be able to test boilerplate with different library versions you can provide 2 additions attributes to this command and specify library versions. +If you want to specify a version of Eightshift Libs or Frontend Libs to use, you can use add two additional attributes to this command to specify a branch or release to use: * `--eightshiftLibsBranch` * `--eightshiftFrontendLibsBranch` #### Example: -If you want to pull a `develop` branch for the Eightshift frontend libs and a specific branch of the Eightshift libs your command will look like this: +If you want to pull the `develop` branch of the Eightshift Frontend libs and a specific release of the Eightshift Libs: ```bash npx create-wp-project --eightshiftLibsBranch="release/3.1.0" --eightshiftFrontendLibsBranch="develop" @@ -50,6 +50,6 @@ npx create-wp-project --help > You can specify both libraries at once or only one. ## What is next? -Now that we have the theme set on your local environment, let's do something with it. +Now that we've set the theme up on your local environment, let's do something with it. Please make sure you read the [Basics chapter](basics/basics-intro) to understand better how the project is set and what is included to make your developing experience as smooth as possible. diff --git a/website/docs/versions.md b/website/docs/versions.md index dfa49dcb1..4c803e1a1 100644 --- a/website/docs/versions.md +++ b/website/docs/versions.md @@ -3,7 +3,7 @@ id: versions title: Versions --- -Now that you understand what makes Eightshift tick, here is a quick reminder about what library versions this documentation refers to. +Now that you understand what makes the Eightshift Development Kit tick, here is a quick reminder about what library versions this documentation refers to. [![docs-source](https://img.shields.io/badge/version--6.0.0-eightshift--boilerplate-red?style=for-the-badge&logo=)](https://github.com/infinum/eightshift-boilerplate) diff --git a/website/docs/welcome.md b/website/docs/welcome.md index 3dc6aed63..0f4f6476e 100644 --- a/website/docs/welcome.md +++ b/website/docs/welcome.md @@ -5,29 +5,40 @@ title: Welcome ## Eightshift Development Kit -Eightshift Development Kit contains all the tools you need to start building a modern WordPress theme, using all the latest front-end and back-end development tools. - -Let's brag a little about what you can expect from this setup: -- **Custom block editor blocks** - Easily use our pre-made, 100% customizable existing block editor blocks & components or create your own. We focus on **dynamic blocks** for developers. -- **OOP** - All code is written following the latest object-oriented programming paradigms (abstract classes, interfaces, dependency injection, namespacing). -- **WP-CLI** - Build your application with pre-made features that you can access with a single command using the terminal. -- **Webpack** - Modern assets & building process that you can customize. -- **SASS** - Easy-to-learn CSS on steroids. -- **Autoprefixing** - You don't have to worry if your code will work on older browsers. -- **JS Compiler (Babel)** - Write JS using the latest features and let Webpack worry about making it work across all browsers. -- **Synchronised browser testing** - Seamless testing in multiple browsers in parallel by using Browser Sync. -- **Minifying** - Automatically minifies your production assets (JS / CSS) during the build process. -- **PHPCS** - Helps you write better code with automatic code linting for PHP, SCSS, and JS. -- **Easy SASS media queries** - Build your application with easy-to-use media queries that are connected to blocks. +Eightshift Development Kit is a modern, developer-friendly solution that makes building large, feature-rich WordPress projects painless. +It contains all the tools you need to start building a modern WordPress theme or plugin, using battle-tested front-end and back-end development tools and practices. + +### Features + +The Eightshift Development Kit provides you with a lot of useful features, so let's take a quick look at some of the core ones: +- **Custom Block Editor blocks** - Using automatic block registration and attribute handling features, building dynamic Gutenberg blocks with the Eightshift Development Kit is a joy. We also provide an extensive library of blocks and components that you can use and customize in your projects. + - **Dynamic blocks** - The Eightshift Development Kit is focused on supporting dynamic blocks, a type of WordPress blocks that are rendered from attributes instead of being serialized as HTML. Dynamic blocks allow you more flexibility when developing and avoid issues with Gutenberg's validation, ensuring you can ship new features and update existing blocks in record time. + - **Components** - Extract commonly used parts into _components_. Manage attributes on the component level. Use powerful composition features to build blocks from multiple components, or even multiple instances of them without worrying about attribute registration. It's a game-changer. + - **The Manifest** - Every block and component has a `manifest.json` file, which is a single source of truth for metadata about your block. +- **Sustainable coding practices** - All our code follows battle-tested programming practices. + - **OOP** - Object-oriented programming is at the core of the Development Kit. Extend our classes or replace them entirely. Need to build a new WP-CLI command? [There's an abstract class for that.](https://github.com/infinum/eightshift-libs/tree/develop/src/Cli) + - **DI** - Eightshift Development Kit ships with a dependency injection container set up out of the box. + - **Code style** - Linters for PHP, JavaScript and SCSS ship out of the box, helping you write better code. Also, all of our code [follows Eightshift Coding Standards](https://github.com/infinum/eightshift-coding-standards/) - consistency assured. + - **Unit tests** - We use Pest and Jest to run unit tests on our code, catching bugs early. + - **Great documentation** - Apart from this website, everything in the code is commented and covered with Docblocks. +- **WP-CLI** - Eightshift Development Kit provides amazing WP-CLI tooling. Import blocks and components from our collection. Build custom commands with ease. Include Development Kit features at will. +- **Frontend build processes** - Eightshift Development Kit comes with Webpack preconfigured. Tweak it to your needs or keep our defaults - it's up to you. Vendor prefixes? Polyfills? SCSS compilation? Asset minification? All taken care of! +- **First-class CSS variables** - Forget about conditional classnames: build out CSS variables from attribute values and scope them to a particular block with almost no code. - **Cache busting** - Each time you build assets, we generate a new URL for each asset file. This means you'll never see the old cached version while developing or after pushing your code to production. +### Parts of the Development Kit -To use it, you need to understand what makes this boilerplate tick. It consists of two parts: +Eightshift Development Kit consists of a few separate projects. It's useful to know what they are, especially if you're contributing to the Development Kit. +#### Eightshift Libs - [docs](eightshift-libs) | [github](https://github.com/infinum/eightshift-libs) -### 1. Eightshift Libs - [docs](eightshift-libs) | [github](https://github.com/infinum/eightshift-libs) +Eightshift Libs handles backend functionality and provides backend support for your projects. This includes abstract classes and interfaces for our core features, dependency injection, asset enqueuing, filter & actions and more. -This is where all the back-end (PHP) code is kept. Think abstract classes, interfaces, dependency injection, namespacing, asset enqueuing, filter & actions. +#### Eightshift Frontend Libs - [docs](eightshift-frontend-libs) | [github](https://github.com/infinum/eightshift-frontend-libs) -### 2. Eightshift Frontend Libs - [docs](eightshift-frontend-libs) | [github](https://github.com/infinum/eightshift-frontend-libs) +Eightshift Frontend Libs houses our frontend code, including various helpers, JavaScript functionality, SCSS styles, and block and component defaults. -This is where all the front-end (JS, SCSS, assets, blocks) code is kept. +#### Boilerplate + +We provide [boilerplates for themes](https://github.com/infinum/eightshift-boilerplate) and [plugins](https://github.com/infinum/eightshift-boilerplate-plugin/), so you can start building your project right away - without manually setting up the libraries above. + +The easiest way to set up the Development Kit is to use the `npx create-wp-project` command, which we'll go into further detail about in the following chapters. diff --git a/website/sidebars.js b/website/sidebars.js index c511604f8..fea706091 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,6 +13,7 @@ module.exports = { 'Basics': [ 'basics/basics-intro', 'basics/wp-cli', + 'basics/architecture-concepts', { 'type': 'category', 'label': 'Backend', @@ -22,7 +23,6 @@ module.exports = { 'basics/extending-classes', 'basics/autowiring', 'basics/example-class', - 'basics/the-structure', 'basics/manifest', { 'type': 'category', diff --git a/website/src/theme/sections/features/features.js b/website/src/theme/sections/features/features.js index c2639e2d5..63d9d8738 100644 --- a/website/src/theme/sections/features/features.js +++ b/website/src/theme/sections/features/features.js @@ -10,57 +10,37 @@ export default function Features() { { icon: 'red', title: 'Custom Block Editor blocks', - desc: 'Easily use our pre-made 100% customizable existing Block Editor blocks & components or create your own. We focus on dynamic blocks for developers.', + desc: 'Build a dynamic block faster than you can say Gutenberg. With automatic block registration and top-notch attribute handling, you\'ll be shipping blocks in record time.', }, { icon: 'purple', - title: 'OOP', - desc: 'All code is written following the latest object-oriented programming paradigms (abstract classes, interfaces, dependency injection, namespacing).', - }, - { - icon: 'yellow', - title: 'WP-CLI', - desc: 'Build your application with all-ready pre-made features that you can access with a single command using the terminal.', - }, - { - icon: 'green', - title: 'Webpack', - desc: 'Modern assets & building process that you can customize.', + title: 'Sustainable, like code should be', + desc: 'All our code follows battle-tested programming practices. OOP? Check. Unit tests? Check. Code docblocks, linters for coding standards and great documentation? Triple check.', }, { icon: 'red', - title: 'SASS', - desc: 'Easy to learn CSS on steroids.', - }, - { - icon: 'purple', - title: 'Autoprefixing', - desc: 'You don\'t have to worry if your code will work on older browsers.', + title: 'OOP: The good way to write PHP code', + desc: 'Object-oriented programming is at the core of Eightshift Development kit, making your projects cleaner and allowing you to extend and replace functionality.', }, { icon: 'yellow', - title: 'JS Compiler (Babel)', - desc: 'Write JS using the latest features and let Webpack worry about making it work across all browsers.', - }, - { - icon: 'red', - title: 'Synchronised browser testing', - desc: 'Automatically minifies your production assets (JS / CSS) during the build process.', + title: 'wp boilerplate', + desc: 'Include features you need, and leave out the ones you don\'t using our powerful WP-CLI tooling.', }, { icon: 'green', - title: 'Minifying', - desc: 'Automatically minifies your production assets (JS / CSS) during the build process.', + title: 'First-class CSS variables', + desc: 'Forget about conditional classnames: build out CSS variables from attribute values and scope them to a particular block with almost no code.' }, { - icon: 'purple', - title: 'PHPCS', - desc: 'Helps you write better code with automatic code linting for PHP, SCSS, and JS.', + icon: 'red', + title: 'A build process to love', + desc: 'Eightshift Development kit comes with Webpack preconfigured, so you can start building your JavaScript and CSS assets from the start. Vendor prefixes? Polyfills? SCSS compilation? Asset minification? All taken care of!' }, { - icon: 'yellow', - title: 'Easy SASS media queries', - desc: 'Build your application with easy to use media queries that are connected to blocks.', + icon: 'purple', + title: 'As responsive as it can get', + desc: 'Declare breakpoints once, use them everywhere — from media queries to blocks. Override any attribute value for particular breakpoints without breaking a sweat. Need to tweak that width for tablets? Done.', }, { icon: 'red', @@ -69,7 +49,7 @@ export default function Features() { }, { icon: 'green', - title: 'Eightshift libs', + title: 'Eightshift Libs', desc: 'Library aimed at bringing the modern development tools to your project.', }, { @@ -106,7 +86,7 @@ export default function Features() { >
diff --git a/website/src/theme/sections/get-started/get-started.js b/website/src/theme/sections/get-started/get-started.js index 44853838d..fa0a5e05a 100644 --- a/website/src/theme/sections/get-started/get-started.js +++ b/website/src/theme/sections/get-started/get-started.js @@ -56,8 +56,8 @@ export default function GetStarted() { >
{items} diff --git a/website/src/theme/sections/panels/panels.js b/website/src/theme/sections/panels/panels.js index 09d6b22a3..c497dc770 100644 --- a/website/src/theme/sections/panels/panels.js +++ b/website/src/theme/sections/panels/panels.js @@ -14,8 +14,8 @@ export default function Panels() { > diff --git a/website/src/theme/sections/showcase-grid/showcase-grid.js b/website/src/theme/sections/showcase-grid/showcase-grid.js index 3daea3c87..0b662d854 100644 --- a/website/src/theme/sections/showcase-grid/showcase-grid.js +++ b/website/src/theme/sections/showcase-grid/showcase-grid.js @@ -94,6 +94,12 @@ export default function ShowcaseGrid() { }, ]); + // https://reactjs.org/docs/react-dom.html#hydrate + const [isClient, setIsClient] = useState(false); + useEffect(() => { + setIsClient(true) + }, []); + const items = itemsData.map((item, index) => { const { image, @@ -130,8 +136,9 @@ export default function ShowcaseGrid() { ) }); + /* key={isClient ? 1 : 2} will trigger a rerender of the whole subtree and the images will be aligned with text */ return ( -
+
diff --git a/website/src/theme/sections/why/why.js b/website/src/theme/sections/why/why.js index a6de51406..bed6f3a4c 100644 --- a/website/src/theme/sections/why/why.js +++ b/website/src/theme/sections/why/why.js @@ -14,8 +14,8 @@ export default function Why() { >