blocks.json

The blocks.json file is used to define and manage custom blocks, styles, and patterns in PorterWP. It primarily helps PorterWP know which folders to scan for custom blocks and also provides options to unregister core blocks, block styles, and patterns, while registering your own.

Structure

The blocks.json file contains the following key sections:

• settings: Defines block categories and folders to scan for custom blocks.

• styles: Registers custom block styles for core or custom blocks, linking them to CSS/SCSS files.

• unregisterStyles: Unregisters default styles from core blocks.

• patterns: Handles custom pattern registration, unregistration, and category management.

• unregisterBlocks: Unregisters core blocks.

Example Structure

{
	"version": "1.0.0",
	"blocks": {
		"settings": {
			"blockCategories": [
                "query-blocks"
                ... // define any custom block categories here
            ],
			"folders": [
                "/components", 
                "/hidden", 
                "/layouts", 
                "/parts", 
                "/query-blocks", 
                "/search", 
                "/structure"
            ]
		},
		"styles": {
			"core/columns": { 
                "LG Row Reverse": {} 
            },
			"core/post-template": {
				"Layout 1": {
					"is_default" : true
				},
				"Layout 2": {}
			},
			"core/post-title" : {
				"Example Title Style": {}
			},
			"core/query-title" : {
				"Example Title Style": {
					"inline_style" : [ "core/post-title", "Example Title Style" ]
				}
			},
		},
		"unregisterStyles": {
			"core/table": ["stripes", "regular"],
			"core/button": ["outline"]
		},
		"patterns": {
			"register": {
				"example/hero": { "title": "Hero" },
				"example/call-to-action": { "title": "Call to action" }
			},
			"unregisterCategories": ["core"],
			"categories": [
                "Example", 
                "Example Synced"
            ]
		},
		"unregisterBlocks": [
			"core/verse"
            ... // unregister any core blocks here
        ]
	}
}

Patterns

Patterns are registered using the patterns.register key, allowing you to specify new block patterns by referencing PHP files. For example:

"patterns": {
	"register": {
		"prefixed/sample-pattern": {
			"title": "Prefixed Sample Pattern"
		}
	}
}

The corresponding pattern file is loaded from /porter/inc/block/patterns/{pattern-name}.php.

Block Styles

Block styles are registered simply by using the following structure, which links to SCSS/CSS files:

"core/paragraph": {
	"Constrain Width": {}
}

This example registers a custom block style called "Constrain Width" for the core/paragraph block, and it will look for a corresponding SCSS file at /porter/inc/block/styles/scss/core_paragraph--constrain-width.scss.

Setting Block Styles as Default and Sharing Styles Between Blocks

In PorterWP, you can not only define custom block styles but also set a block style as the default for a specific block. Additionally, you can apply a style from one block to another block by referencing the style. This is useful when you want to ensure consistent styling across different blocks without duplicating code.

Setting a Default Block Style

To set a block style as the default for a block, you can add the "is_default": true key to the desired style. Here's an example of setting "Layout 1" as the default style for the core/post-template block:

"core/post-template": {
	"Layout 1": {
		"is_default": true
	},
	"Layout 2": {}
}

In this example, "Layout 1" will automatically be applied as the default style for the core/post-template block unless the user manually selects another style.

Sharing Styles Between Blocks

You can also "steal" or share styles from one block to another. This is done by referencing the block and style you want to inherit from using the inline_style key.

Here’s an example where the core/query-title block steals the "Example Title Style" from the core/post-title block:

"core/post-title": {
	"Example Title Style": {}
},
"core/query-title": {
	"Example Title Style": {
		"inline_style": ["core/post-title", "Example Title Style"]
	}
}

In this example, the core/query-title block will apply the same styling as the "Example Title Style" defined for the core/post-title block.

Key Points:

• is_default: Automatically applies the defined style as the default for a block.

• inline_style: Shares or "steals" styles from another block by referencing the block and style name in an array format: [block, style_name].

This approach helps maintain consistency across blocks without duplicating style definitions.

SCSS File Generation

PorterWP can automatically generate the corresponding SCSS file for any custom block style using Gulp. When gulp watch is running, PorterWP looks for changes in block.json and generates SCSS files with default content for any block styles declared in block.json.