{"id":21989191,"url":"https://github.com/micropackage/block-loader","last_synced_at":"2025-04-30T11:30:24.761Z","repository":{"id":48992484,"uuid":"236566828","full_name":"micropackage/block-loader","owner":"micropackage","description":"Automatic WordPress Gutenberg block loader based on template files","archived":false,"fork":false,"pushed_at":"2022-03-19T19:25:05.000Z","size":63,"stargazers_count":24,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2024-10-29T06:06:53.855Z","etag":null,"topics":["acf","bracketspace","composer-library","gutenberg","meta-box","micropackage"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/micropackage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-27T18:51:00.000Z","updated_at":"2023-10-18T15:32:14.000Z","dependencies_parsed_at":"2022-09-09T03:10:50.889Z","dependency_job_id":null,"html_url":"https://github.com/micropackage/block-loader","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fblock-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fblock-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fblock-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fblock-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micropackage","download_url":"https://codeload.github.com/micropackage/block-loader/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227105514,"owners_count":17731748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acf","bracketspace","composer-library","gutenberg","meta-box","micropackage"],"created_at":"2024-11-29T19:28:20.690Z","updated_at":"2025-04-30T11:30:24.732Z","avatar_url":"https://github.com/micropackage.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Block Loader\n\n[![BracketSpace Micropackage](https://img.shields.io/badge/BracketSpace-Micropackage-brightgreen)](https://bracketspace.com)\n[![Latest Stable Version](https://poser.pugx.org/micropackage/block-loader/v/stable)](https://packagist.org/packages/micropackage/block-loader)\n[![PHP from Packagist](https://img.shields.io/packagist/php-v/micropackage/block-loader.svg)](https://packagist.org/packages/micropackage/block-loader)\n[![Total Downloads](https://poser.pugx.org/micropackage/block-loader/downloads)](https://packagist.org/packages/micropackage/block-loader)\n[![License](https://poser.pugx.org/micropackage/block-loader/license)](https://packagist.org/packages/micropackage/block-loader)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://bracketspace.com/extras/micropackage/micropackage-small.png\" alt=\"Micropackage logo\"/\u003e\n\u003c/p\u003e\n\nRequires WordPress \u003e=5.8.0.\n\n## 🧬 About Block Loader\n\nBlock Loader loads the Gutenberg Block configuration directly out of the block template file. It parses the file header comment figuring out hwo to register the Block.\n\nBasically instead doing this:\n\n```php\nacf_register_block_type( [\n\t'name'              =\u003e 'sample-block',\n\t'title'             =\u003e __('Sample Block'),\n\t'render_template'   =\u003e 'blocks/sample-block.php',\n] );\n```\n\nYou can do initialize the loader once:\n\n```php\nMicropackage\\BlockLoader\\BlockLoader::init( [\n\t'dir' =\u003e 'blocks',\n] );\n```\n\nAnd define the block config directly in the template (`blocks/sample-block.php`):\n\n```\n\u003c?php\n/**\n * Block Name: Sample Block\n */\n\n...\n```\n\n**Supported plugins:**\n- Advanced Custom Fields\n- Meta Box\n\n---\n\nThis micropackage is compatible with [ACF Block Creator](https://github.com/micropackage/acf-block-creator/) which can create the block templates for you while defining the Field group for your new block.\n\n## 💾 Installation\n\n``` bash\ncomposer require micropackage/block-loader\n```\n\n## 🕹 Usage\n\nBefore you can start creating blocks you need to initiate the block loader passing optional config array:\n\n```php\nMicropackage\\BlockLoader\\BlockLoader::init( [\n\t'dir'        =\u003e 'blocks',\n\t'categories' =\u003e [],\n\t'wrap'       =\u003e '\u003cdiv id=\"%3$s\" class=\"%2$s\"\u003e%1$s\u003c/div\u003e', // ACF only\n] );\n```\n\nBlocks are based on the template files located by default in `blocks` folder in your theme (you can change that).\n\nThere are two steps to create a block:\n1. Create block template file in the `blocks` folder\n2. Define custom fields for your block using ACF or Meta Box.\n\nBlock template file needs to have a comment header containing block parameters.\n\n```\n\u003c?php\n/**\n * Block Name: (required)\n * Description:\n * Category:\n * Icon:\n * Keywords: (comma-separated)\n * Post Types: \t(comma-separated, ACF only)\n * Mode: (ACF only)\n * Align: (ACF only)\n * Enqueue Style:\n * Enqueue Script:\n * Enqueue Assets:\n * Supports Align: (comma-separated)\n * Supports Anchor: (true|false)\n * Supports Custom Class Name: (true|false)\n * Supports Mode: (true|false, ACF only)\n * Supports Multiple: (true|false)\n * Supports Reusable: (true|false)\n * Supports Spacing: (true)\n */\n```\n\n### ACF\n\nCreating template files is enough for ACF to register blocks. After that you only need to create new fields group and set it's location to your custom block.\n\n### Meta Box\n\nIn Meta Box you need \"MB Blocks\" extension to work with blocks.\nWith this plugin custom fields are defined in code. You need to use `rwmb_meta_boxes` filter to create metabox for your block.\n\nLet's say you have a template called `blocks/some-block.php`. You need to add the fields definition like this:\n\n```php\nadd_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {\n\t$meta_boxes[] = [\n\t\t'id'     =\u003e 'some-block',\n\t\t'type'   =\u003e 'block',\n\t\t'fields' =\u003e [\n\t\t\t// ...fields configuration\n\t\t],\n\t];\n\n\treturn $meta_boxes;\n} );\n```\n\nAll block parameters will be fetched from template header comment and merged with your fields configuration.\n\n## ⚙️ Configuration\nAll parameters are optional.\n\n| Parameter                  | Type              | Description                                                  |\n| -------------------------- | ----------------- | ------------------------------------------------------------ |\n| **dir**                    | (*string*)        | This is a directory within your theme where block templates are located. Relative path.\u003cbr/\u003e**Default:** `'blocks'` |\n| **categories**             | (*array*)         | Array of custom block categories passed directly to [`block_categories_all`](https://developer.wordpress.org/reference/hooks/block_categories_all/) filter.\u003cbr /\u003eIf only one category will be configured, it will be used as default category for all custom blocks.\u003cbr /\u003e**Default:** `[]` (empty array) |\n| **wrap**                   | (*false\\|string*) | Wrapper to each block. If set to false, the block content will be just the template file content.\u003cbr/\u003eWorks only for ACF due to the differences in block rendering mechanisms.\u003cbr/\u003e**Default:** `'\u003cdiv id=\"%3$s\" class=\"%2$s\"\u003e%1$s\u003c/div\u003e'` |\n| `...$block_creator_params` | -                 | Additional parameters passed to [ACF Block Creator](https://github.com/micropackage/acf-block-creator/) |\n\n### Categories definition\n\nThis is how to define the categories array.\n\n```php\n\t...\n\t'categories' =\u003e [\n\t\t[\n\t\t\t'slug'  =\u003e 'custom-cat',\n\t\t\t'title' =\u003e __( 'Custom Category', 'textdomain' ),\n\t\t\t'icon'  =\u003e 'book-alt',\n\t\t],\n\t\t...\n\t],\n\t...\n```\n\n### Wrap template\n\nParameters used in internal `sprintf`:\n\n1. block content from template file, which should be wrapped\n2. block classes string\n3. unique block id\n\nExample: `'\u003cdiv id=\"%3$s\" class=\"%2$s\"\u003e%1$s\u003c/div\u003e'`\n\n## 📦 About the Micropackage project\n\nMicropackages - as the name suggests - are micro packages with a tiny bit of reusable code, helpful particularly in WordPress development.\n\nThe aim is to have multiple packages which can be put together to create something bigger by defining only the structure.\n\nMicropackages are maintained by [BracketSpace](https://bracketspace.com).\n\n## 📖 Changelog\n\n[See the changelog file](./CHANGELOG.md).\n\n## 📃 License\n\nGNU General Public License (GPL) v3.0. See the [LICENSE](./LICENSE) file for more information.\n\n## © Credits\n\nThe Loader engine is based on the [palmiak](https://github.com/palmiak)'s [Timber ACF WP Blocks](https://github.com/palmiak/timber-acf-wp-blocks).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicropackage%2Fblock-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicropackage%2Fblock-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicropackage%2Fblock-loader/lists"}