{"id":15631795,"url":"https://github.com/log1x/poet","last_synced_at":"2025-04-12T21:26:24.136Z","repository":{"id":40813385,"uuid":"220766341","full_name":"Log1x/poet","owner":"Log1x","description":"Configuration-based post type, taxonomy, block category, and block registration for Sage 10.","archived":false,"fork":false,"pushed_at":"2024-06-05T23:37:38.000Z","size":87,"stargazers_count":204,"open_issues_count":5,"forks_count":16,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-30T01:37:44.422Z","etag":null,"topics":["blocks","custom-post-types","custom-taxonomies","gutenberg","sage10","wordpress"],"latest_commit_sha":null,"homepage":"https://github.com/Log1x/poet","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Log1x.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"Log1x"}},"created_at":"2019-11-10T09:11:09.000Z","updated_at":"2024-10-29T10:09:39.000Z","dependencies_parsed_at":"2023-11-17T00:49:00.434Z","dependency_job_id":"91b653bb-2b7c-448f-bbe6-6389030f226c","html_url":"https://github.com/Log1x/poet","commit_stats":{"total_commits":59,"total_committers":13,"mean_commits":4.538461538461538,"dds":"0.23728813559322037","last_synced_commit":"537649337e6a628991cf10effde1d9e34fbe3a27"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Log1x%2Fpoet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Log1x%2Fpoet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Log1x%2Fpoet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Log1x%2Fpoet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Log1x","download_url":"https://codeload.github.com/Log1x/poet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248633486,"owners_count":21136877,"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":["blocks","custom-post-types","custom-taxonomies","gutenberg","sage10","wordpress"],"created_at":"2024-10-03T10:41:35.491Z","updated_at":"2025-04-12T21:26:24.112Z","avatar_url":"https://github.com/Log1x.png","language":"PHP","funding_links":["https://github.com/sponsors/Log1x"],"categories":[],"sub_categories":[],"readme":"# Poet\n\n![Latest Stable Version](https://img.shields.io/packagist/v/log1x/poet?style=flat-square)\n![Total Downloads](https://img.shields.io/packagist/dt/log1x/poet?style=flat-square)\n![Build Status](https://img.shields.io/github/actions/workflow/status/log1x/poet/Main.yml?branch=master\u0026style=flat-square)\n\nPoet provides simple configuration-based post type, taxonomy, editor color palette, block category, block pattern and block registration/modification.\n\n## Features\n\n- Dead simple post type and taxonomy registration, modification, and unregistering powered by [Extended CPTs](https://github.com/johnbillion/extended-cpts).\n- Easy editor color palette configuration including built-in support for [webpack-palette-plugin](https://github.com/roots/palette-webpack-plugin).\n- Blocks registered are rendered using Laravel Blade on the frontend.\n- Block Patterns registered can have their content defined using Laravel Blade too.\n- Add additional block categories with nothing more than a slug.\n- Move parent admin menu items to the `Tools` submenu using their page slug.\n\n## Requirements\n\n- [Sage](https://github.com/roots/sage) \u003e= 10.0\n- [PHP](https://secure.php.net/manual/en/install.php) \u003e= 7.4\n- [Composer](https://getcomposer.org/download/)\n\n## Installation\n\nInstall via Composer:\n\n```bash\n$ composer require log1x/poet\n```\n\n## Getting Started\n\nStart with publishing the Poet configuration file using Acorn:\n\n```bash\n$ wp acorn vendor:publish --provider=\"Log1x\\Poet\\PoetServiceProvider\"\n```\n\n## Usage\n\n### Registering a Post Type\n\nAll configuration related to Poet is located in `config/poet.php`. Here you will find an example Book post type pre-configured with a few common settings:\n\n```php\n'post' =\u003e [\n    'book' =\u003e [\n        'enter_title_here' =\u003e 'Enter book title',\n        'menu_icon' =\u003e 'dashicons-book-alt',\n        'supports' =\u003e ['title', 'editor', 'author', 'revisions', 'thumbnail'],\n        'show_in_rest' =\u003e true,\n        'has_archive' =\u003e false,\n        'labels' =\u003e [\n            'singular' =\u003e 'Book',\n            'plural' =\u003e 'Books',\n        ],\n    ],\n],\n```\n\nIn it's simplest form, a post type can be created by simply passing a string:\n\n```php\n'post' =\u003e [\n    'book',\n],\n```\n\nTo modify an existing post type, simply treat it as if you are creating a new post type passing only the configuration options you wish to change:\n\n```php\n'post' =\u003e [\n    'post' =\u003e [\n        'labels' =\u003e [\n            'singular' =\u003e 'Article',\n            'plural' =\u003e 'Articles',\n        ],\n    ],\n],\n```\n\nIt is also possible to unregister an existing post type by simply passing `false`:\n\n```php\n'post' =\u003e [\n    'book' =\u003e false,\n],\n```\n\nPlease note that some built-in post types (e.g. Post) can not be conventionally unregistered.\n\nFor additional configuration options for post types, please see:\n\n- [`register_post_type()`](https://developer.wordpress.org/reference/functions/register_post_type/)\n- [`register_extended_post_type()`](https://github.com/johnbillion/extended-cpts/wiki/Registering-Post-Types)\n\n\u003e **Note**: Do not nest configuration in a `config` key like shown in the Extended CPTs documentation.\n\n### Registering a Taxonomy\n\nRegistering a taxonomy is similar to a post type. Looking in `config/poet.php`, you will see a Genre taxonomy accompanying the default Book post type:\n\n```php\n'taxonomy' =\u003e [\n    'genre' =\u003e [\n        'links' =\u003e ['book'],\n        'meta_box' =\u003e 'radio',\n    ],\n],\n```\n\nThe most relevent configuration option is `links` which defines the post type the taxonomy is connected to. If no link is specified, it will default to `post`.\n\nTo view an archive for the Genre taxonomy, copy the Blade template called `archive.blade.php` to a new file called `taxonomy-genre.blade.php`.\n\nIn it's simplest form, you can simply pass a string. The example below would create a Topic taxonomy for the Post post type:\n\n```php\n'taxonomy' =\u003e [\n    'topic',\n],\n```\n\nAs with post types, to modify an existing taxonomy, simply pass only the configuration options you wish to change:\n\n```php\n'taxonomy' =\u003e [\n    'category' =\u003e [\n        'labels' =\u003e [\n            'singular' =\u003e 'Section',\n            'plural' =\u003e 'Sections',\n        ],\n    ],\n],\n```\n\nAlso like post types, you can easily unregister an existing taxonomy by simply passing `false`:\n\n```php\n'taxonomy' =\u003e [\n    'post_tag' =\u003e false,\n    'category' =\u003e false,\n],\n```\n\nFor additional configuration options for taxonomies, please see:\n\n- [`register_taxonomy()`](https://developer.wordpress.org/reference/functions/register_taxonomy/)\n- [`register_extended_taxonomy()`](https://github.com/johnbillion/extended-cpts/wiki/Registering-taxonomies)\n\n\u003e **Note**: Do not nest configuration in a `config` key like shown in the Extended CPTs documentation.\n\n### Registering a Block\n\nPoet provides an easy way to register a Gutenberg block with the editor using an accompanying Blade view for rendering the block on the frontend.\n\nBlocks are registered using the `namespace/label` defined when [registering the block with the editor](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype).\n\nIf no namespace is provided, the current theme's [text domain](https://developer.wordpress.org/themes/functionality/internationalization/#loading-text-domain) will be used instead.\n\nRegistering a block in most cases is as simple as:\n\n```php\n'block' =\u003e [\n    'sage/accordion',\n],\n```\n\n#### Creating a Block View\n\nGiven the block `sage/accordion`, your accompanying Blade view would be located at `views/blocks/accordion.blade.php`.\n\nBlock views have the following variables available:\n\n- `$data` – An object containing the block data.\n- `$content` – A string containing the InnerBlocks content. Returns `null` when empty.\n\nBy default, when checking if `$content` is empty, it is passed through a method to remove all tags and whitespace before evaluating. This assures that editor bloat like `nbsp;` or empty `\u003cp\u003e\u003c/p\u003e` tags do not cause `$content` to always return `true` when used in a conditional.\n\nIf you do not want this behavior on a particular block, simply register it as an array:\n\n```php\n'block' =\u003e [\n    'sage/accordion' =\u003e ['strip' =\u003e false],\n],\n```\n\nIf you need to register block attributes using PHP on a particular block, simply pass the attributes in an array when registering:\n\n```php\n'block' =\u003e [\n    'sage/accordion' =\u003e [\n        'attributes' =\u003e [\n            'title' =\u003e [\n                'default' =\u003e 'Lorem ipsum',\n                'type' =\u003e 'string',\n            ],\n        ],\n    ],\n],\n```\n\nConsider an accordion block that is registered with a `title` and `className` attribute. Your view might look something like this:\n\n```php\n\u003cdiv class=\"wp-block-accordion {{ $data-\u003eclassName ?? '' }}\"\u003e\n  @isset ($data-\u003etitle)\n    \u003ch2\u003e{!! $data-\u003etitle !!}\u003c/h2\u003e\n  @endisset\n\n  \u003cdiv\u003e\n    {!! $content ?? 'Please feed me InnerBlocks.' !!}\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Registering a Block Category\n\nPoet provides an easy to way register, modify, and unregister Gutenberg block categories. Looking in the config, you will see a commented out example for a Call to Action category:\n\n```php\n'block_category' =\u003e [\n    'cta' =\u003e [\n        'title' =\u003e 'Call to Action',\n        'icon' =\u003e 'star-filled',\n    ],\n],\n```\n\nThis would result in a block category with a slug of `cta`. Once your block category is registered, you must register a block to its slug before the category will appear in the editor.\n\nIn it's simplest form, you can simply pass a string:\n\n```php\n'block_category' =\u003e [\n    'my-cool-blocks',\n],\n```\n\nwhich would result in a `my-cool-blocks` category automatically converting the slug to title case.\n\nYou can also specify the title by passing a value to your slug:\n\n```php\n'block_category' =\u003e [\n    'my-cool-blocks' =\u003e 'Best Blocks, World.',\n],\n```\n\nLike post types and taxonomies, modifying an existing block category is the same as registering one:\n\n```php\n'block_category' =\u003e [\n    'layouts' =\u003e 'Sections',\n    'common' =\u003e ['icon' =\u003e 'star-filled'],\n],\n```\n\nYou can unregister an existing block category by simply passing `false`:\n\n```php\n'block_category' =\u003e [\n    'common' =\u003e false,\n],\n```\n\n### Registering a Block Pattern\n\nPoet can also register Block Patterns for you, with an optional Blade view for the content.\n\nPatterns are registered using the `namespace/label` defined when [registering the pattern with the editor](https://developer.wordpress.org/reference/functions/register_block_pattern/).\n\nIf no namespace is provided, the current theme's [text domain](https://developer.wordpress.org/themes/functionality/internationalization/#loading-text-domain) will be used instead.\n\nRegistering a block in most cases is as simple as:\n\n```php\n'block_pattern' =\u003e [\n    'sage/hero' =\u003e [\n        'title' =\u003e 'Page Hero',\n        'description' =\u003e 'Draw attention to the main focus of the page, and highlight key CTAs',\n        'categories' =\u003e ['all'],\n    ],\n],\n```\n\nYou can register the actual content for the pattern here as well, using the `content` key. Or leave it blank to use a corresponding blade view.\n\n```php\n'block_pattern' =\u003e [\n    'sage/fake-paragraph' =\u003e [\n        'title' =\u003e 'Fake Paragraph',\n        'description' =\u003e 'Filler content used instead of actual content for testing purposes',\n        'categories' =\u003e ['all'],\n        'content' =\u003e '\u003c!-- wp:paragraph --\u003e\u003cp\u003eLorem ipsum dolor sit amet, consectetur adipisicing elit. Ratione nulla culpa repudiandae nisi nostrum et, labore earum repellendus porro, mollitia voluptas quam? Modi sint tempore deleniti nesciunt ab, perferendis et.\u003c/p\u003e\u003c!-- /wp:paragraph --\u003e',\n    ],\n],\n```\n\n#### Creating a Pattern View\n\nGiven the block `sage/fake-paragraph`, if no `content` key is defined, then your accompanying Blade view would be located at `views/block-patterns/fake-paragraph.blade.php`.\n\nThis Block Pattern view may look like this:\n\n```php\n\u003c!-- wp:paragraph --\u003e\n\u003cp\u003eLorem ipsum dolor sit amet, consectetur adipisicing elit. Ratione nulla culpa repudiandae nisi nostrum et, labore earum repellendus porro, mollitia voluptas quam? Modi sint tempore deleniti nesciunt ab, perferendis et.\u003c/p\u003e\n\u003c!-- /wp:paragraph --\u003e\n```\n\n### Registering a Block Pattern Category\n\nBlock Pattern Categories can be added with the following code in the poet config:\n\n```php\n'block_pattern_category' =\u003e [\n    'all' =\u003e [\n        'label' =\u003e 'All Patterns',\n    ],\n],\n```\n\nYou can specify all category properties such as `label`, as per the [block editor handbook](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/#register_block_pattern_category).\n\n\u003e Note: Currently, if no Block Pattern Categories are available at all, the Block Patterns tab in the editor will crash when clicked on.\n\n### Registering an Editor Color Palette\n\nPoet attempts to simplify registering a color palette with the editor a bit by not requiring such strict, fragile array markup.\n\nWhile you can of course pass said array directly, you are also able to register colors by simply passing a slug along with a color and letting Poet handle the rest.\n\n```php\n'palette' =\u003e [\n    'red' =\u003e '#ff0000',\n    'blue' =\u003e '#0000ff',\n],\n```\n\nAlternatively to passing an array, Poet also accepts a `JSON` file containing your color palette. Poet will generally look for this file in `dist/` by default.\n\n```php\n'palette' =\u003e 'colors.json',\n```\n\nIf you are using the [Palette Webpack Plugin](https://github.com/roots/palette-webpack-plugin), you may also simply pass `true` to automatically use the generated `palette.json` during build.\n\n```php\n'palette' =\u003e true,\n```\n\n## Bug Reports\n\nIf you discover a bug in Poet, please [open an issue](https://github.com/log1x/poet/issues).\n\n## Contributing\n\nContributing whether it be through PRs, reporting an issue, or suggesting an idea is encouraged and appreciated.\n\n## License\n\nPoet is provided under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flog1x%2Fpoet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flog1x%2Fpoet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flog1x%2Fpoet/lists"}