@goodwp/goodenberg
v0.2.1
Published
Goodenberg is a library of components, helpers and examples for building modern WordPress sites and applications with the block editor and all other features introduced with Gutenberg.
Downloads
93
Readme
Goodenberg
Goodenberg is a library of components, helpers and examples for building modern WordPress sites and applications with the block editor and all other features introduced with Gutenberg.
Warning
This package is under active development and not considered stable, breaking changes can be added. I'm using the package on a few sites and some custom plugins successfully, but am still developing, optimizing and documenting it at the moment.
Table of Contents
Versioning / Supported WordPress versions
The library will follow SemVer versioning. Major versions and breaking changes will be kept to a minimum. Each minor version will support the latest stable WordPress version at the time of release. Development versions will try to work with newer Gutenberg versions.
Current supported WordPress version: WordPress 6.5
JavaScript / React
All JavaScript code is developed inside the src
directory.
Usage
- Install the package via
npm install @goodwp/goodenberg
- Use
@wordpress/scripts
for an easy build process and to automatically extract dependencies - Use single components/hooks/etc
- All submodules (see below) can be imported from the submodules entrypoint
import {Page} from "@goodwp/goodenberg/admin/components";
- All submodules also provide directory-based imports:
import {Page} from "@goodwp/goodenberg/admin/components/page";
- All submodules (see below) can be imported from the submodules entrypoint
Architecture
The library only uses babel with the @wordpress/babel-preset-default
preset to transpile each single js file, but does
not have any other build-process. It is suggested to use
@wordpress/scripts or a custom webpack config to bundle it.
Styles are created via @emotion to avoid requiring an additional stylesheet.
Components (components
)
React components to be used in your admin screens or custom blocks.
- EntityRecordsSelect: A component which allows a user to select multiple records ( post, term, etc.).
- EntityRecordSelect: A component which allows a user to select a single record ( post, term, etc.).
Admin (admin
)
React components, hooks, and utils for building pages in the wp-admin. Useful for building custom plugin pages, settings pages, etc. To be used together with @wordpress/components.
Components
Page: A component to build a complete wp-admin page, including header, content, notices.
Page.Header: A header bar for wp-admin pages.
AdminNotices: A "slot" which will render all admin notices that were rendered on the server
Bar: A full-width navigation bar for headers/footers on admin pages (used in Page.Header).
Container: A centered container which has a configurable default max-width.
TabPanel: A styled version of WordPress TabPanel component to be used on admin pages right beneath your Page.Header.
Router
A simple "router" to render some components based on a current active "route". There are two implementations (one for URL-based routing, on for state-based routing). Both provide a similar API.
Hooks (hooks
)
React hooks to be used in your admin screens or custom blocks.
useApiFetch
: A hook wrapper around theapiFetch
function from core.useLocation
/useHistory
: A hook to use the URL/window.location and history object to use browser navigation.
Utils (utils
)
Handy utility functions.
getBlockStyle(className: string)
: Get the selected/applied block style by its classname.onBlockRegistration(blockName, namespace, callback)
: Allows hooking into the registerBlockType hook of a specific block. Avoid having to check for the block name in your callback.onBlockEdit(blockName, namespace, callback, higherOrderComponent = false)
: Allows hooking into the BlockEdit hook of a specific block. Avoid having to check for the block name in your callback.
PHP
All PHP code is developed inside the lib
directory.
Usage
- Install the package via
composer require goodwp/goodenberg
- Load your composers autoload file in your plugin/theme.
- Use the classes and helpers.
Examples
The examples directory contains a plugin which uses a lot of the components. You can also test this plugin via @wordpress/env:
- Clone the repository
- Run
npm install
- Run
npm env:start
- Open
http://localhost:8888/wp-admin
and login withadmin
/password
- Activate the plugin and open the example pages.
You can also use WordPress Playground to directly see the examples in a browser:
- Download the examples plugin from the latest release.
- Go to https://playground.wordpress.net/
- Upload and activate the plugin
- Go to the new admin page "Goodenberg examples"
Bugs, Issues, Security Issues, Feature Requests
Visit our GitHub Repository.
Inspired by 10up/block-components.