2 5 Registering a Block

imath edited this page Jan 13, 2019 · 2 revisions

Making your Block ready for the Entrepôt.

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.

Example of a block.json file

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/"
    }
}

The name property

Required. It's the name of your block.

The author property

Required. It needs to be your GitHub username e.g. https://github.com/{username}/{repository}.

The github_url property

Required. It's the cloning URL of your block e.g. https://github.com/{username}/{repository}.git.

The version property

Required. The version property will be used to check whether there is an update of your block available.

The block_id property

Required. It's the ID of your block. It will be used when registering it into the block editor.

The php_relative_path property

Optional. If you need to include some PHP code, this property lets you set the relative path to the PHP file to load.

The render_callback property

Optional. If your block is dynamic, you need to use this property to inform about the rendering callback to call for your dynamic block.

The attributes property

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.

The editor_script property

Required. It's an object describing the main JavaScript of your block.

handle

Required. Used to register your script into WordPress.

relative_path

Required. It's the relative path to your main JavaScript file.

dependencies

Optional. It's an array of the JavaScript handles your script has dependencies on.

The editor_style property

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:

handle

Required. Used to register your style into WordPress.

relative_path

Required. It's the relative path to your CSS file.

dependencies

Optional. It's an array of the style handles your style has dependencies on.

The style property

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:

handle

Required. Used to register your style into WordPress.

relative_path

Required. It's the relative path to your CSS file.

dependencies

Optional. It's an array of the style handles your style has dependencies on.

The translations property

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.

Registering to the Entrepôt

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"
}

The name, author, slug, releases and issues properties

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.

The author property

It needs to be your GitHub username e.g. https://github.com/{username}/{repository}.

The description property

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.

The tags property

Unused for now. Depending on the popularity of the Entrepôt and the number of registered blocks, filtering blocks by tags will be implemented.

The README property

Optional (but advised!). Used when a user clicks on the "Name of your block" link of your block's card.

The dependencies property

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+" }
],

The urls property

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.