-
Notifications
You must be signed in to change notification settings - Fork 7
2 5 Registering a Block
Since version 1.5.0 of the Entrepôt, you can know register standalone Blocks.
Entrepôt is using a specific process to install and upgrade the block you wish to register. The easiest part of this process is to include in your block's GitHub repository a JSON file named block.json containing all the properties the Entrepôt needs to load your Block files into WordPress.
Thanks to the Entrepôt you can focus on the JavaScript/CSS parts of your block and rely on it to register and enqueue your scripts, styles and translations without writing a single line of PHP !
If your block is dynamic and needs some PHP code, you simply need to set a specific property about the relative path to the PHP file containing your rendering callback and set another property with the name of the function of this rendering callback and the Entrepôt will take care of loading everything into WordPress.
Below is the block.json file used by the Formulaire de Recherche block.
{
"name": "Formulaire de Recherche",
"author": "imath",
"github_url": "https://github.com/imath/formulaire-de-recherche.git",
"version": "1.0.0",
"block_id": "formulaire-de-recherche/recherche",
"php_relative_path": "lib/functions.php",
"render_callback": "formulaire_de_recherche_render_callback",
"attributes": {
"title" : {
"type": "string"
},
"align" : {
"type": "string"
}
},
"editor_script": {
"handle": "formulaire-de-recherche-block",
"relative_path" : "dist/js/index.js",
"dependencies": [
"wp-editor"
]
},
"editor_style": {
"handle": "formulaire-de-recherche-editor-style",
"relative_path" : "dist/css/editor-style.css",
"dependencies": []
},
"style": {
"handle": "formulaire-de-recherche-style",
"relative_path" : "dist/css/style.css",
"dependencies": []
},
"translations": {
"text_domain": "formulaire-de-recherche",
"domain_path": "languages/"
}
}Required. It's the name of your block.
Required. It needs to be your GitHub username e.g. https://github.com/{username}/{repository}.
Required. It's the cloning URL of your block e.g. https://github.com/{username}/{repository}.git.
Required. The version property will be used to check whether there is an update of your block available.
Required. It's the ID of your block. It will be used when registering it into the block editor.
Optional. If you need to include some PHP code, this property lets you set the relative path to the PHP file to load.
Optional. If your block is dynamic, you need to use this property to inform about the rendering callback to call for your dynamic block.
Optional. If you use the ServerSideRender component into your block, you need to provide an object to describe the attributes of your block. Each attribute name needs to be the key of the object and you need to inform about the type of this attribute eg: string.
NB: the different available types are the one used into the WordPress REST API.
Required. It's an object describing the main JavaScript of your block.
Required. Used to register your script into WordPress.
Required. It's the relative path to your main JavaScript file.
Optional. It's an array of the JavaScript handles your script has dependencies on.
Optional. If your block needs to include some CSS to shape itself into the Editor screen of the WordPress administration, you need to describe the following properties:
Required. Used to register your style into WordPress.
Required. It's the relative path to your CSS file.
Optional. It's an array of the style handles your style has dependencies on.
Optional. If your block needs to include some CSS to shape itself into the Editor screen of the WordPress administration and into the front-end part of the website, you need to describe the following properties:
Required. Used to register your style into WordPress.
Required. It's the relative path to your CSS file.
Optional. It's an array of the style handles your style has dependencies on.
Optional. If you internationalized your block, you need to provide the text domain you choose for your block and the path to the folder to find the available translations. For more informations about how to generate script translations, read this post.
Once you've set this block.json file, you can add your block's folder into the wp-content/blocks directory the Entrepôt creates to store block folders. Go to the Block Types WordPress Administration screen to activate your block form the Installed tab. You'll then be able to develop or debug your block.
To register your block you simply need to submit a Pull Request on this repository to add a JSON file containing all the informations Entrepôt will need to install and keep your block up to date on users' WordPress sites.
This file will need to be added to the /repositories/blocks directory. The name of the JSON file needs to be the same as the slug parameter of the JSON object. For instance the Formulaire de recherche block is using /repositories/blocks/formulaire-de-recherche.json as the name for this file.
{
"name": "Formulaire de Recherche",
"author": "imath",
"slug": "formulaire-de-recherche",
"icon": "https://raw.githubusercontent.com/imath/formulaire-de-recherche/master/icon.png",
"tags": [
"search",
"form"
],
"country": "fr_FR",
"releases": "https://github.com/imath/formulaire-de-recherche/releases",
"issues": "https://github.com/imath/formulaire-de-recherche/issues",
"description": {
"en_US" : "A block to insert a basic search form into WordPress posts.",
"fr_FR" : "Un bloc pour intégrer un formulaire de recherche dans vos publications WordPress."
},
"README": "https://raw.githubusercontent.com/imath/formulaire-de-recherche/master/README.md"
}These properties are required. They will be used in your block's card inside the Block Types WordPress Administration screen the Entrepôt is adding to the dashboard.
It needs to be your GitHub username e.g. https://github.com/{username}/{repository}.
It will be used in your block's card inside the Block Types WordPress Administration screen the Entrepôt is adding to the dashboard. This is required. You need to include at least the american (en_US) version of the description of your block.
Unused for now. Depending on the popularity of the Entrepôt and the number of registered blocks, filtering blocks by tags will be implemented.
Optional (but advised!). Used when a user clicks on the "Name of your block" link of your block's card.
Optional. This property allows you to display the plugin/theme/WordPress version dependencies of your block type. It's an array of objects where the object key is the name of the function that needs to be available for your block type to run. The value is the lugin/theme/WordPress version name of your dependency. You can have more than one dependency. For instance here is the dependencies parameter of the BP Idea Stream plugin:
"dependencies": [
{ "bp_get_displayed_user": "BuddyPress 2.6+" },
{ "wp_idea_stream_upgrade_to_2_4": "WP Idea Stream 2.4+" }
],Optional. This property allows you to display more links into the modal that pops when a user clicks on the "Name of your block" link of your block's card. You can include a link to the CHANGELOG.md, a donate link, and a link to the Wiki of your repository.
- User Guides
- Installation
- Entrepôt Plugin repositories
- Admin Notices center
- Plugin version manager
- Entrepôt Theme repositories
- Entrepôt Block repositories
- Developer Guides