humanmade/hm-gutenberg-tools

Useful helpers, components or tools for building things with Gutenberg

Human Made Gutenberg Tools

A place to bundle useful reusable Gutenberg components and other tools.

What does this include?

• Post Select button. Provides a media modal like user experience for selecting single or multiple posts. It supports searching, filtering, sorting and custom post types (and taxonomies). stying to work better in the sidebar.
• More Sidebar controls. Other components wrapped up in as standardised sidebar control components.
  • Link control. A wrapper for the core UrlInput, but with some style improvements.
  • Image. Sidebar UI for selecting an image.
  • Post. A wrapper for the post select button component.

Installation Instructions

It is reccomended to install as a plugin or mu-plugin using composer.

composer require humanmade/hm-gutenberg-tools

If you install using another method (e.g. git submodule), note that the main branch does not include built assets, but tagged releases and the build branch do include them. You should not need to build the assets for this plugin as part of your project build process.

Bundling in a theme

You can bundle the plugin in a theme (or anywhere outside of plugins/mu-plugins directories). In order to do this you need to define HM_GB_TOOLS_DIR and HM_GB_TOOLS_URL. For example

define( 'HM_GB_TOOLS_DIR', get_stylesheet_directory() . '/lib/hm-gutenberg-tools' );
define( 'HM_GB_TOOLS_URL', get_stylesheet_directory_uri() . '/lib/hm-gutenberg-tools' );

Using components from HM Gutenberg Tools

You should specify the script hm-gb-tools-editor as a dependency of the script in which you are using it.

wp_enqueue_script( 'my-custom-block', plugins_url( 'my-custom-block.js', dirname(__FILE__) ), [ 'hm-gb-tools-editor' ], '1.0' );

HM Gutenberg Tools then exposes all functionality globally as window.hm. You can then use reference this in your project in much the the same way that you would use any other components from Gutenberg.

const { PostSelectButton } = window.hm.components;

function Edit( { attributes, setAttributes } ) {
    return (
        <PostSelectButton
            value={ attributes.postIds }
            onSelect={ posts => setAttributes( { postIds: posts.map( p => p.id ) } ) }
            postType="page"
            btnProps={ { isLarge: true } }
        >
    );
}

Refer to the Wiki for usage instructions on individual components

Development

• npm run build Builds a production version of the code.
• npm run watch Watches for changes and builds development versions of the code.
• npm run lint Lints your JS. Run npm run lint -- --fix to fix it too.
• composer run lint Lints your PHP code.

To assist with local development, you can define define( 'HM_GB_TOOLS_DEV', true ); to enable the "HM Gutenberg Tools Dev" block, which includes examples of many of features offered by this plugin.

Releasing a new version.

1. Update the version numbers in plugin.php and package.json.
2. Add the changelog to the readme for the new version.
3. Commit your changes to main and push.
4. Run the bash script: ./release.sh v1.2.3

The script will sync the the build branch with main, build assets and commit the changes, and publish a new tagged version.

Changelog

v1.7.3

• Restore built asset files not included in v1.7.2 due to release process error.

v1.7.2

• Upgraded dependencies for enhanced performance, security and stability.
• Audit fix dependency upgrade, improving code security.
• Enhanced security by introducing sanitization for post.title.rendered mitigating XSS attack risks.

v1.7.1

• Add filter for minimum search length for term select.
• Add filter for term select query.

v1.7.0

• Add post status field select.
• Allow to accept status from the Rest API endpoint.
• Add status field in the post list item.
• Update deprecated mediaUpload function.

v1.6.3

• Ignore sticky posts by default.

v1.6.2

• Fix date filter label not being cleared when both selected dates are unset.
• Switch from node-sass to sass and npm audit fix

v1.6.1

• Reset PostSelect current page when filters are changed

v1.6.0

• Adds date range filters for use when searching posts

v1.5.0

• Handle current selections across multiple post types
• Correctly handle post type filters in post selection modal
• Preserbe specified Post Type list when clearing Types token list

v1.4.1

• Adds a filter to allow the post select query to be modified

v1.4.0

• Support thumbnails in post select components

v1.3.1

• Switch selection when clicking off single-post selections

v1.1.0

• Support for i18n.

v1.0.0

• Refactor how it works for compatability with WordPress 5.0
  • Use core data store
  • Use custom endpoint to fetch content to handle multiple post types.

v0.2.0

• Deprecate EditableHTML. You can now just use the Gutenberg component wp.editor.RichText and set the format prop to string.
• Updates to work with the latest version of Gutenberg (3.5).

hm-gutenberg-tools's Issues

ReferenceError: Backbone is not defined

I get this error when I install hm-gutenberg-tools plugin

I don't know much about backbone but is there anything that backbone can do that react can't do ?

Post Tags not searching correctly

Currently Post Tags don't have live search.

When searching it only searches the tags currently loaded.

Search functionality needs to search all tags regardless of if they are loaded.

Make it possible to filter posts by date range

Context

Date range filters would help narrow down the number of posts returned by the Post Select component.

This is particularly helpful when you don't know the exact title and maybe the keywords you have are common among several posts. So combining those keywords and a date range in addition to taxonomies will refine the search results much more.

Technical brief

• Create a form-field-date component here
• Component to have a DatePicker for use in picking start and end date that'll be used to search for a post
• Two instances of the component to be added here for the start and end dates respectively
• Default date to be null so that if no dates are found in the filters then the search won't include dates
• The values of those FormFieldDate components to be publishedAfter and publishedBefore respectively
• onChange of those components to use onUpdateFilters to update the values of those two dates
• Retrieve the publishedAfter and publishedBefore on the postSelect endpoint here
• If either publishedAfter is not empty or publishedBefore is not empty, set date_query after and before parameters of the query here respectively
• Post Select button to receive a showDateFilters prop that controls whether the filters are shown on Select modal or not

Acceptance Criteria

• Two date pickers show up on the select a post modal
• Setting one of the dates should filter the posts correctly based on that date
• Setting both dates should filter posts to include only the posts in the date range
• Date range filters should be an optional addition depending on how Post Select button is setup

Using UNSAFE_componentWillReceiveProps in strict mode is not recommended

Having updated to the latest release (1.2.4), I'm seeing this console warning when rendering the post select UI

Warning: Using UNSAFE_componentWillReceiveProps in strict mode is not recommended and may indicate bugs in your code. See https://fb.me/react-unsafe-component-lifecycles for details.

* Move data fetching code or side effects to componentDidUpdate.
* If you're updating state whenever props change, refactor your code to use memoization techniques or move it to static getDerivedStateFromProps. Learn more at: https://fb.me/react-derived-state

Please update the following components: r, t

Allow to filter the post by Post Status

We need to incorporate an additional selection field status for the post, as shown below:

In certain scenarios, users may want to include future, pending, or scheduled posts in their post list. Once these selected posts are published, they will become visible to the public.

Refactor components to use Context API

Discussion from issue #89 PR resulted in the suggestion to refactor components to use Context API so as to avoid messy prop drilling from root component.

CurrentSelection component doesn't show selected posts for multiple post types

When the postType prop of PostSelectButton is array of multiple post types, CurrentSelection doesn't show the selected posts. This happens because the CurrentSelection components uses getEntityRecords(), which doesn't allow multiple post types to be queried at once.

Move release process to GitHub Action

Following a mistake during our execution of the deploy steps for v1.7.2, that version of this plugin went live without built assets. That caused errors in downstream projects which used hm.controls.PostControl as a dependency.

To avoid human error, we should update this project to use a GitHub Action-based release workflow that publishes the built tag and release in an automated fashion.

question on Post Select button capacity

Hi
Thanks for sharing this plugin.
I have one question on Post Select button capacity
How many posts or pages can Post Select display.
For example if I had 500 posts. Is there a pagination for high number posts ? is there a limit ?

PHP 7.4 compatibility errors

When running PHP compatibility check for 7.4 we have the following errors reported, as per our Altis V7 upgrade guide we will need to address these:

FILE: /Users/tareiking/projects/fujitv/content/mu-plugins/hm-gutenberg-tools/inc/endpoints/class-post-select-controller.php
---------------------------------------------------------------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
---------------------------------------------------------------------------------------------------------------------------
 185 | ERROR | Extension 'mysql_' is deprecated since PHP 5.5 and removed since PHP 7.0; Use mysqli instead
 194 | ERROR | Extension 'mysql_' is deprecated since PHP 5.5 and removed since PHP 7.0; Use mysqli instead
---------------------------------------------------------------------------------------------------------------------------

Display post author in the post list item

Display real post author in the post list results.

Just a placeholder right now.

Proper post type is added here #19

Issue for adding real date is here: #20

HM_GB_TOOLS_PATH isn't defined

The HM_GB_TOOLS_PATH constant is used in HM\GutenbergTools\enqueue_block_editor_assets(), but it isn't defined anywhere.

Question on your article

Hi Matthew I've read your article 'Gutenberg on Humanmade.com' and I was impressed by the work you've done here. I have one question about the stat block I've seen in the video, there is 'add new stat' button and close one on each stat. Do you reuse gutenberg component for that or do you create your own one with react state ?
I find it very useful to give the possibity to add or remove component in gutenberg but so far in gutenberg I just find the delete block option.
I don't know gutenberg very well so maybe I'm wrong

Current Selection component gets "Unhandled promise rejection" error

• WP version: 5.2.2
• HM Gutenberg Tools version: 1.1.0

I'm seeing an "Unhandled promise rejection" error from the following line of code:

hm-gutenberg-tools/js/current-selection/index.js

Line 11 in 09019bf

const posts = getEntityRecords( 'postType', postType, { include: postIds } );

This is the error details:

Unhandled promise rejection 
Object { code: "rest_invalid_param", message: "Invalid parameter(s): include", data: {…} }

The issue is that the postIds array is not returning an array of ID's (integers). Instead, it's returning an array of arrays, and each array is the post object's data (id, title, type, date, slug, etc.).

When the Current Selection component is calling getEntityRecords, it is passing postIds as the include parameter, but that expects an array of integers, which is why it is throwing an error.

Since all of the post data is already in the postIds array, it seems like maybe there is no need for the withSelect for this component. Unless, of course, the real underlying issue is that the postIds array should be an array of ID's instead of an array of post objects.

[Request] Installation guide

Would be helpful :)

Not really clear on why this isn't published on npm

NODE_ENV variables are not supported in windows OS.

Hello Folks,

I was testing this tool on my windows machine, I have installed node, npm package and then when I tried to run command yarn build I got the bunch of errors.

In below code, It seems node environments variable are not supported in Windows OS.

hm-gutenberg-tools/package.json

Line 9 in 9c4046a

"js:build": "NODE_ENV=production webpack",

Possible Solution

Adding npm package such as https://www.npmjs.com/package/cross-env would solve the issue.

Ref:
https://www.npmjs.com/package/cross-env

Frame buttons alignment

On Firefox, the buttons are correctly right-aligned, but on Chrome, they're left-aligned.

Avoid monolithic lodash import

This is low-priority, but we currently consume lodash by installing the full package and then pulling in just the libraries we need, for example import _isEqual from 'lodash/isEqual. These imports could be changed to depend on the standalone lodash modules such as lodash.isequal, to reduce how much needs to be installed when building.

filemtime warning

Hi Matthew I install hm-gutenberg-tools as plugin and I get filemtime warnings

Uncaught ReferenceError: hm is not defined (Gutenberg 3.7)

In using PostControls, the below no longer works with Gutenberg 3.7

const { PostControl } = hm.controls;

PostSelect - Pagination offset remains after changing search query

Steps to Reproduce

1. Open the post browser, where there are multiple pages of posts
2. Click "Next page" to go to page 2 (with search query still blank)
3. Change query from blank to some query A, where there is only one page of relevant search results

Expected

1. Search results will show the user the most relevant search results (i.e. the first page)

Actual:

1. Search result says "No results found", though a "previous page" button is present.

The above also occurs for queries where there is more than one page of relevant search results, in which case the user is instead shown the that Nth page rather than the first page. I would like to propose that the page be set back to the first page of results when any of the filters are changed, to reduce user interaction necessary to view the most relevant search results, and to preempt confusion in the case of seeing less-relevant or empty search results when a new search is started.

Will create a PR for review implementing the above proposal.

License is unclear

What license is this project under?

Fix `externals` entry in Webpack config

Somwehere between version 2.4.0 and 2.6.0, Gutenberg remove ReactDOMServer from its externals entry in Webpack config. Since one of HMGT's components is relying on that, we need to also remove it from our externals. Otherwise the built script will throw error and the hm global will not be set.

Make it possible to modify the posts select query

Context

There is a use case where it may be required to filter posts by searching for the search string in the title only. The default behaviour of WP_Query is that it searches for the search string both in the title and in the content of a post. Therefore it should be possible to modify the behaviour of the query to cater for this use case or any other use cases that require the query to be modified.

Technical brief

• Add two actions before and after WP_Query here to give other plugins or themes the ability to modify the query.

Acceptance criteria

• Any other plugin or theme can modify the query to alter the returned results e.g limit the query to search only in title for a keyword as seen here.

Post Selection Button: hm not defined

In Gutenberg 4.5.1

const { PostSelectButton } = hm.components;

is leading to "Uncaught ReferenceError: hm is not defined". Have HM Gutenberg tools installed and activated as a plugin.

Please advise thanks so much

Images

ReferenceError: hm is not defined

Hi
I try to use your postselectbutton component like this:

const { __ } = wp.i18n; // Import __() from wp.i18n
const { registerBlockType } = wp.blocks; // Import registerBlockType() from wp.blocks
const { PostSelectButton } = hm.components;

and then I use it in edit:

edit: function( props ) {
		// Creates a <p class='wp-block-gb-basic-esnext-02'></p>.
		return (
			<PostSelectButton 
			    value={ value }
			    onSelect={ value => setAttributes( { value } ) }
			    postType="post" 
			    btnProps={ { isLarge: true } }
			/>
		);
	},

but it gives me ReferenceError: hm is not defined
I thought that hm were install globally when I activate your plugin.

Display proper post type on post list

Add date to post list item

Display real post date in the post list results.

Just a placeholder right now.

Proper post type is added here #19

Post Type filter is lost when clearing token list

Steps to Reproduce

1. Set up a PostSelect button with a post type list of [ 'post', 'some custom post type' ].
2. Observe that when you click the PostSelect button, "page" or other post types do not display
3. Select "post" in the token list for Post Type in the left column, and filter
4. Clear "post" from the token list with the × button, and then filter again

What happens
"page" items, and other post type items not part of the original filter list, now appear in the results

What I expected
I'd see the same list of only Post and the specified CPT items as when I first opened the modal

Install with composer

Hi,

I see that the package isn't installable with composer, what about publishing it on packagist.org?

Duplicate taxonomy filter in multi post type search

I use multi-post-type branch.

Let's say I register a new taxonomy called genre for post and page types.
<?php register_taxonomy( 'genre', array( 'post', 'page' ), $args ); ?>

When searching for a post, the genre taxonomy filter is shown twice.

I'd expect the filter to be shown only once as it's common for both post types.

Change how Post Tags search works

Currently post tag search works as the following:

• Order is by id
• Character limit search is 3 characters minimum

What we need to do:
Default Post Tag order in Gutenberg is count we need to make sure that when searching inside the Filter by Tag field to be ordered by count

For languages such as Japanese the character limit can be as small as 1 or 2 characters before returning a result

ReactDOMServer and hm is not defined

Hi
I use this code

const { __ } = wp.i18n;
const { registerBlockType } = wp.blocks;
const { PostSelectButton } = hm.components;

registerBlockType( 'gb/esnext-hm', { 
    title: 'hm-gutenberg',
    icon: 'shield', 
    category: 'common',

    attributes: {
        myAttr: { type: 'string' }
    },


    edit( { attributes, setAttributes } ) {

         const { myAttr } = attributes;
         function onSelectContent( newValue ) {
            setAttributes( { myAttr: newValue } );
        }
        return (
            <PostSelectButton
                value={ myAttr }
                onSelect={ onSelectContent }
                postType="post"
                maxPosts = "10"
                btnProps={ { isLarge: true } }
            >{ __( 'Button text' ) }
        </PostSelectButton>

        );
    },
    save: function( props ) {
        return (
            <p className={ props.className }>Hello World! — from the frontend (02 Basic Block ESNext).</p>
        );
    },
} );

and enqueue like this

add_action( 'enqueue_block_editor_assets', 'gutenberg_examples_03_esnext_enqueue_block_editor_assets' );

function gutenberg_examples_03_esnext_enqueue_block_editor_assets() {
	wp_enqueue_script(
		'gutenberg-examples-03_esnext',
		plugins_url( 'block.build.js', __FILE__ ),
		array( 'wp-blocks', 'wp-i18n', 'wp-element','hm-gb-tools-editor' ),
		filemtime( plugin_dir_path( __FILE__ ) . 'block.build.js' )
	);

	wp_enqueue_style(
		'gutenberg-examples-03_esnext-editor',
		plugins_url( 'editor.css', __FILE__ ),
		array( 'wp-edit-blocks','hm-gb-tools-editor' ),
		filemtime( plugin_dir_path( __FILE__ ) . 'editor.css' )
	);
}

and I get these two errors
ReferenceError: ReactDOMServer is not defined editor.bundle.js:1:211169
ReferenceError: hm is not defined block.build.js:73:5

Bug: persistant date label after unsetting dates

There is a bug where the label above the "Edit date filter" button isn't cleared after unsetting dates. Steps to reproduce:

• Click "Edit date filter" button
• Select a date in both date pickers
• Click "Confirm" button
• The label above the "Edit date filter" button should show text that has the two selected dates
• Click "Edit date filter" button again
• Click both "Unset" button for the date pickers
• Click "Confirm" button
• The label above the "Edit date filter" will remain but this shouldn't be the case

Acceptance criteria

• The final result of repeating the steps mentioned above should be the label above the "Edit date filter" button will be cleared.