edit-flow / BLOCKS.md

BLOCKS.md in Edit Flow 0.9, at BLOCKS.md

127 lines 3.6 KB

Raw Download Zip

1	# Block Editor Compatibility
2
3	This file describes steps to start developing Blocks for Edit Flow.
4	Currently, the following Edit Flow modules are compatible with Gutenberg Block Editor:
5
6	* Custom Status
7
8	### Setup
9
10	Note: This document assumes you have a working knowledge of modern JavaScript and its tooling, including: npm, Webpack, and, of course, React.
11
12	Prerequisites: `npm`, `yarn` (optionally).
13
14	From the plugin's folder run:
15
16	```
17	npm i
18	```
19
20	or
21
22	```
23	yarn
24	```
25
26	This should leave you with everything you need for development, including local copy of Webpack and webpack-cli.
27
28
29	## Anatomy of an Edit Flow block.
30
31	There are two parts for Block Editor compatibility implementation for each module.
32
33	#### PHP
34
35	TL;DR; check out
36	[](modules/custom-status/custom-status.phpCustom Status Module](modules/custom-status/custom-status.php](modules/custom-status/custom-status.php) and its corresponding [](modules/custom-status/compat/block-editor.phpBlock Editor Compat](modules/custom-status/compat/block-editor.php](modules/custom-status/compat/block-editor.php) for the working example.
37
38	On the PHP side, in the module's folder create a `compat` sub-folder, and in it, create a file named `block-editor.php`.
39
40	That file has to contain the class ${EF_Module_Class_Name}_Block_Editor_Compat.
41	E.g., for the `Custom Status` Module, which class name is `EF_Custom_Status`, the compat class name has to be `EF_Custom_Status_Block_Editor_Compat`.
42
43
44	Here's a contrived example of a fictional module:
45
46	`modules/fictional-module/fictional-module.php`:
47
48	```php
49	<?php
50	class EF_Fictional_Module {
51	protected $compat_hooks = [
52	'admin_enqueue_scripts' => 'module_admin_scripts'
53	];
54
55	function module_admin_scripts() {
56	// something-something, not compatible with Gutenberg
57	}
58	}
59	```
60
61	`modules/fictional-module/compat/block-editor.php`:
62
63	```php
64	<?php
65	class EF_Fictional_Module_Block_Editor_Compat {
66	// @see in "common/php/trait-block-editor-compatible.php
67	use Block_Editor_Compatible;
68
69	// Holds the reference to the module, so that we can use the module's logic.
70	$ef_module;
71
72	function module_admin_scripts() {
73	$this->ef_module->do_something_with_module();
74	}
75	}
76	```
77
78	Important
79
80	To avoid class inheritance complexities, Edit Flow compat files use a trait [](common/php/trait-block-editor-compatible.phpBlock_Editor_Compatible](common/php/trait-block-editor-compatible.php](common/php/trait-block-editor-compatible.php). Be sure to check it out before implementing compatibility for other modules.
81
82	##### How does it work?
83
84	Each Edit Flow module follows the same pattern: attaching the necessary hooks for actions and filters on instantiation.
85
86	We have modified the loader logic in the main Edit_Flow class to try to instantiate the Block_Editor_Compat for corresponding module.
87
88	This way the code for existing modules doesn't need to be modified, except adding the `protected $compat_hooks` property.
89
90	On the instantiation of the module's compatibility class, we'll iterate over `$compat_hooks` and remove the hooks registered by the module, and add ones defined in the compat class.
91
92	#### JavaScript
93
94	##### Development
95
96	To start the Webpack in watch mode:
97
98	```npm run dev```
99
100	##### Build for production
101
102	To generate optimized/minified production-ready files:
103
104	```npm run build```
105
106	##### File Structure
107
108	```
109	blocks/
110	# Source files:
111	src/
112	module-slug/
113	block.js # Gutenberg Block code for the module
114	editor.scss # Editor styles
115	style.scss # Front-end styles
116	# Build
117	dist/
118	module-slug.build.js # Built block js
119	module-slug.editor.build.css # Built editor CSS
120	module-slug.style.build.css # Built front-end CSS
121	```
122
123	The files from `dist/` should be enqueued in the compat class for the module.
124
125	See [](modules/custom-status/compat/block-editor.phpCustom Statuses Compatibility Class](modules/custom-status/compat/block-editor.php](modules/custom-status/compat/block-editor.php) for implementation details.
126
127	Please note: this is a Work-In-Progress, most likely there will be major changes in the near future.