PHPackages viget/viget-blocks-toolkit - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. viget/viget-blocks-toolkit ActiveWordpress-plugin[Utility & Helpers](/categories/utility) viget/viget-blocks-toolkit ========================== Simplifying Block Registration and other block editor related features. v1.1.6(1mo ago)7879↓10.7%MITPHPCI failing Since Jan 14Pushed 1mo ago5 watchersCompare [ Source](https://github.com/vigetlabs/viget-blocks-toolkit)[ Packagist](https://packagist.org/packages/viget/viget-blocks-toolkit)[ Docs](https://github.com/vigetlabs/viget-blocks-toolkit)[ RSS](/packages/viget-viget-blocks-toolkit/feed)WikiDiscussions main Synced 3d ago READMEChangelog (10)Dependencies (3)Versions (19)Used By (0) Viget Blocks Toolkit ==================== [](#viget-blocks-toolkit) This toolkit was made to simplify the process of registering custom blocks with ACF Pro. It also adds several additional features to the block editor such as Block Icons and Breakpoint Visibility. Creating Custom Blocks in your Theme ------------------------------------ [](#creating-custom-blocks-in-your-theme) To create a block in your theme, simply create a `blocks` folder in the root of your theme directory. Each block should have its own folder and a `block.json` file. The `block.json` file should contain the [block configuration](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/). You can then use a `render.php` file (or `render.twig` file if Timber/Twig is supported) to render the block. By default, the blocks that support `jsx` will automatically render using the plugin's `jsx.php` file. ### Customizations [](#customizations) #### `block.json` [](#blockjson) ##### tagName [](#tagname) Useful when using the built-in render file for `jsx` supported blocks, `tagName` can be set in `block.json` to specify the outer tag for the block. (By default it uses `section`). ##### innerContainer [](#innercontainer) You can disable the inner container wrapper by setting the value of `innerContainer` in `supports` to `false`. ##### blockId [](#blockid) Assign each block a unique, persistent `blockId` simply by adding the attribute to the `block.json` file. ##### mediaPosition [](#mediaposition) Adding the `mediaPosition` attribute will enable the Media Position toggle buttons in the block toolbar and apply transforms based on the `mediaPosition: transformations` array in the `supports` object. The transformations rules will apply: - Root level transformations will apply to all child blocks. - `reverse` will reverse the order of the child blocks. - `attributes` will modify the block's attributes. - Each value will be determined based on the value of `mediaPosition`. See example below. - Nested `innerBlocks` will apply transformations only to child blocks when present within the parent block. In the following example scenario: - All columns will be reversed. - All buttons will have their layout justified based on the `mediaPosition` value. (`mediaPosition` is on the left, the attribute value is on the right) - Any images within a column block will have their alignment switched based on the `mediaPosition` value. ``` { "supports": { "mediaPosition": { "transformations": [ { "core/columns": { "reverse": true } }, { "core/buttons": { "attributes": { "layout": { "justifyContent": { "left": "right", "right": "left" } } } } }, { "core/column": { "innerBlocks": [ { "core/image": { "attributes": { "align": { "left": "right", "right": "left" } } } } ] } } ] } } } ``` This is an example of a `block.json` file with all the supported customizations. ``` { "tagName": "article", "attributes": { "blockId": { "type": "string", "default": "" }, "mediaPosition": { "type": "string", "default": "left" } }, "supports": { "innerContainer": false, "mediaPosition": { "transformations": [ { "core/columns": { "reverse": true } } ] } } } ``` #### `blockPattern` [](#blockpattern) You can set a `blockPattern` attribute default in `block.json` to seed `` from block markup instead of `template.json`. Resolution order: 1. Registered pattern slug (exact match). 2. If the value contains `/`, the basename is checked as a registered slug. 3. If still not found, look for a local file in `patterns/`: - `{slug}.php` - `{slug}.html` - `{slug}.twig` (when Timber is available) Both namespaced (`wp-starter/cta-default`) and basename (`cta-default`) values are supported. #### `templateLock` [](#templatelock) Set a `templateLock` attribute default in `block.json` to pass through to ``. When set to `"contentOnly"`, the toolkit automatically passes that lock value to `inner_blocks()` render calls so ACF blocks can behave like content-only container blocks. #### `lock` [](#lock) Set a default `lock` object on the parent block and it will be recursively applied to seeded child blocks unless a child already defines its own `lock` value. ``` { "attributes": { "lock": { "type": "object", "default": { "move": false, "remove": true } } } } ``` #### `sync` [](#sync) Set a `sync` attribute to `true` when the `blockPattern` markup should be the render-time source of truth (instead of saved inner block content). This is optional and defaults to `false`. #### `template.json` fallback [](#templatejson-fallback) If there is a `template.json` file present, the contents of `template` are used as the `innerBlocks` template when `blockPattern` is not provided. Example: ``` { "template": [ [ "core/heading" ], [ "core/paragraph" ] ] } ``` #### `block.php` [](#blockphp) If there a `block.php` file present, it will automatically be loaded during block registration. #### `render.php` [](#renderphp) There are several variables available in the `render.php` file: ``` /** * @global array $block The block data. * @global array $context The block context data. * @global bool $is_preview Whether the block is being previewed. * @global int $post_id The current post ID. (Be careful, you may want to use $context['postId'] when in a loop) * @global \WP_Block $wp_block The WP_Block object. */ ``` The `$block` variable also has some additional values: ``` $block['url'] // The URL to the block folder. $block['path'] // The path to the block folder. $block['template'] // The template.json file contents. $block['templateLock'] // The runtime template lock value for inner blocks. $block['blockPattern'] // The block pattern slug used for editor seeding/render sync. $block['lock'] // Default lock object propagated to nested blocks. $block['sync'] // Whether render-time pattern sync is enabled. $block['slug'] // The slug of the block, without the `acf/` prefix. ``` Breakpoint Visibility --------------------- [](#breakpoint-visibility) This block settings panel is available on any supported block in the Full Site Editor and in post block editor. It allows you to set visibility for each block at different breakpoints, so blocks can be hidden or shown based on the screen size. There is a setting to also specify a breakpoint and whether the block should be hidden or shown at that breakpoint. When a parent block is using `templateLock: "contentOnly"`, quick visibility and icon controls remain available in block toolbar controls. Main Helper Functions --------------------- [](#main-helper-functions) ### `vgtbt()` [](#vgtbt) Returns an instance of the Viget Blocks Toolkit `Core` class. ```