DEV Community: Ryan Welcher

Introduction to WordPress SlotFill

Ryan Welcher — Fri, 20 Nov 2020 13:37:43 +0000

In 2019, I was lucky enough to speak at the fantastic JavaScript for WordPress conference. It was my first virtual conference and I had a really great time. It’s a great conference so check it out this year!

Here is the recording and you can see the associated repo here

The post Introduction to WordPress SlotFill appeared first on Ryan Welcher.

Limiting the block count for InnerBlocks

Ryan Welcher — Fri, 09 Oct 2020 18:44:00 +0000

One of the most versatile components that Gutenberg block developers have is the <InnerBlocks/> component. This component allows other blocks to be inserted into it. WordPress Core ships with the Group and Columns blocks that both use InnerBlocks internally to allow the creation of very complex block structures.

The InnerBlocks component solves some interesting problems for custom blocks, for example creating a list of ordered items. By leveraging InnerBlocks, one can skip having to build a bespoke system and rely on Gutenberg to handle the insertion, deletion, and ordering of items. It is very flexible and easy to use. However, while working with it I discovered that there is no built-in way to limit the number of blocks that can be inserted.

The renderAppender prop will allow us to solve this issue

RenderAppender Overview

Before we talk about the solution, let briefly discuss the renderAppender prop and how it works.

Released with WordPress. 5.3, the renderAppender prop allows us to control the interface for inserting blocks into the related <InnerBlocks/> component.

There are two predefined appenders available in WordPress core:

<InnerBlocks.DefaultBlockAppender />
<InnerBlocks.ButtonBlockAppender />

As the name indicates, this is the default appender. If the renderAppender prop is undefined, then this is the appender that is used. It automatically inserts whichever block is configured as the default block via wp.blocks.setDefaultBlockName – which by default is the Paragraph block.

If you’ve worked in the block editor at all you’ve already seen this.

Look familiar?

So when working with <InnerBlocks/>, you don’t need to pass anything to renderAppender to get this style of appender. If fact, you can leave it off entirely.

<InnerBlocks />

This appender is displayed as a + ( plus ) icon button that, when clicked, displays the block inserter. This appender does not insert a default block.

This appender is seen in the Group or Columns block.

Groups and Column blocks use InnerBlocks.ButtonBlockAppender

To use this in your <InnerBlocks/>, you have to pass a function to renderAppender that returns the <InnerBlocks.ButtonBlockAppender /> component.

<InnerBlocks
    renderAppender={ () => (
        <InnerBlocks.ButtonBlockAppender />
     ) }
/>

No appender at all

The last option is to pass false to renderAppender to not display any appender at all.

<InnerBlocks
    renderAppender={false}
/>

Solution

Now that we have an understanding of how the renderAppender prop works, let us use it to solve the problems of limiting the number of blocks allowed.

After some experimentation, the actual solution is fairly straight forward, we just need a way to count how many blocks have been inserted and if it’s more than we want, we set renderAppender to false so that nothing is displayed and the user cannot insert any more blocks until one is removed.

The core/block-editor datastore provides a getBlock()selector that we can use to get the information we need. We pass it the clientId of our block and we can get the list of innerBlocks, count them, and either display the appender or return false.

Below is the code that you would place into the edit property of a block, it’s very simple and but demonstrates the the solution.

import { useSelect } from '@wordpress/data';
import { InnerBlocks } from '@wordpress/block-editor';

const InnerBlockWithLimit = ( props ) => {
    const { clientId } = props;
    const innerBlockCount = useSelect( ( select ) => select( 'core/block-editor' ).getBlock( clientId ).innerBlocks );

    const appenderToUse = () => {
        if ( innerBlockCount.length < 10 ) {
            return (
                <InnerBlocks.ButtonBlockAppender/>
            );
        } else {
            return false;
        }
    }

    return (
        <InnerBlocks
            renderAppender={ () => appenderToUse() }
        />
    )
}

Have you seen any other issues when working with <InnerBlocks/> or want to discuss this approach? If so, leave a comment below!

The post Limiting the block count for InnerBlocks appeared first on Ryan Welcher.

Restricting PluginDocumentSettingPanel by post type

Ryan Welcher — Fri, 21 Feb 2020 15:10:54 +0000

Now that the PluginDocumentSettingPanel is in WordPress core, we can add our own panels to the Document Settings panel using the registerPlugin function.

const { registerPlugin } = wp.plugins;
const { PluginDocumentSettingPanel } = wp.editPost;

const MyCustomSideBarPanel = () => (
    <PluginDocumentSettingPanel
        name="my-custom-panel"
        title="My Custom Panel"
    >
        Hello, World!
    </PluginDocumentSettingPanel>
);
registerPlugin( 'my-custom-panel', {render: MyCustomSideBarPanel } );

The above code will insert a new Panel in the Document Sidebar with the title of “My Custom Panel ” and will display “ Hello, World! ” as it’s content. If we want this panel to appear on every post type registered, then we’re done but what if we want to restrict this panel to just a single post type?

To do this, we’ll need to know what the current post type is and then only render this SlotFill if it’s the correct post type. So how can we do this?

Two Solutions

In order to get access to the post type, we will need to leverage wp.data.select() function. This can be done directly as seen above it’s better to use either the withSelect Higher-Order Component or the newer useSelect Hook. We’ll look at both here.

withSelect

withSelect is a Higher Order Component that will allow us to give our custom component some new functionality.

const CustomSideBarPanelwithSelect = withSelect( ( select ) => {
    return {
        postType: select( 'core/editor' ).getCurrentPostType(),
    };
} )( MyCustomSideBarPanel );

Examining the above, we can see that withSelect takes a function as a parameter that returns a props object contain items that will be merged with the Component that is being wrapped, MyCustomSideBarPanel, and returns the augmented component. Which we’re callingCustomSideBarPanelWithSelect.

So with that in mind, we need to update MyCustomSideBarPanel to accept the new postType props being passed to it:

const MyCustomSideBarPanel = ( { postType } ) => (
    <PluginDocumentSettingPanel
        name="my-custom-panel"
        title="My Custom Panel"
    >
        Hello, World!
    </PluginDocumentSettingPanel>
);

Once we have this in place, we just need to update the logic inside the Component to look for the proper post type before rendering.

const MyCustomSideBarPanel = ( { postType } ) => {

    if ( 'post-type-name' !== postType ) {
        return null;
    }

    return(
            <PluginDocumentSettingPanel name="my-custom-panel" title="My Custom Panel">
        Hello, World!
        </PluginDocumentSettingPanel>
    );
}

Full Code:

const { registerPlugin } = wp.plugins;
const { PluginDocumentSettingPanel } = wp.editPost
const { withSelect } = wp.data;

const MyCustomSideBarPanel = ( { postType } ) => {

    if ( 'post-type-name' !== postType ) {
        return null;
    }

    return(
        <PluginDocumentSettingPanel
            name="my-custom-panel"
            title="My Custom Panel"
        >
            Hello, World!
        </PluginDocumentSettingPanel>
    );
}

const CustomSideBarPanelwithSelect = withSelect( select => {
    return {
        postType: select( 'core/editor' ).getCurrentPostType(),
    };
} )( MyCustomSideBarPanel);

registerPlugin( 'my-custom-panel', { render: CustomSideBarPanelwithSelect } );

useSelect

The useSelect hook is a newer addition to Gutenberg and greatly simplifies the code required to set up access to the post type. The only change we need to make to our existing component is to add the check inside:

const { registerPlugin } = wp.plugins;
const { PluginDocumentSettingPanel } = wp.editPost
const { useSelect } = wp.data;

const MyCustomSideBarPanel = () => {
const postType = useSelect( select => select( 'core/editor' ).getCurrentPostType() );

    if ( 'post-type-name' !== postType ) {
        return null;
    }

    return(
        <PluginDocumentSettingPanel
            name="my-custom-panel"
            title="My Custom Panel"
        >
            Hello, World!
        </PluginDocumentSettingPanel>
    );
}
registerPlugin( 'my-custom-panel', { render: MyCustomSideBarPanel } );

Similar to withSelect, useSelect takes a function as a parameter that returns whatever you want to be stored. In our case, we just need the result of calling select('core/editor').getCurrentPostType().

Hope this helps!

The post Restricting PluginDocumentSettingPanel by post type appeared first on Ryan Welcher.

Better Unit Testing with DataProviders

Ryan Welcher — Tue, 06 Dec 2016 03:45:10 +0000

When unit testing your code, there are times when you need to test the same method or function with a variety of different parameters. For example, we have a function to check to see if a passed email is both valid and not already in the list of known emails:

/**
 * Confirm that a new email is both valid and not already in a list of known email addresses.
 *
 * @param string $new_email The new email we're going to add.
 * @param array $list_of_saved_emails The list of currently saved emails to check against.
 *
 * @return bool
 */
function is_new_and_valid_email( $new_email, $list_of_saved_emails ) {

    if ( ! filter_var( $new_email, FILTER_VALIDATE_EMAIL ) ) {
        return false;
    }

    if ( in_array( $new_email, $list_of_saved_emails, true ) ) {
        return false;
    }

    return true;
}

We can run a simple test on this by creating a new test class:

/**
 * Class Simple_Tests
 */
class Simple_Tests extends PHPUnit_Framework_TestCase {

    /**
     * Simple unit test with hardcoded values
     */
    function test_is_new_and_valid_email_new_email() {
        $expected_result = true;
        $actual_result = is_new_and_valid_email( 'new@email.com', array( 'alternate@email.com' ) );

        $this->assertSame( $expected_result, $actual_result );
    }
}

The test above will pass but it doesn’t cover all of the possibilities that this function could run into in the real world. What happens if the email already exists or is not a real email? We need those tests too.

We have a couple of options to create those tests:

Write a new test function for each possible combination.
Use a DataProvider and run the same test using that data it provides.

Option 1: Write more tests.

Let’s start by looking at the first option. We will need to write a new assertion for each of the possible cases. Which looks like this:

/**
 * Simple unit test with hardcoded values
 */
function test_is_new_and_valid_email_new_email() {
   $expected_result = true;
   $actual_result = is_new_and_valid_email( 'new@email.com', array( 'alternate@email.com' ) );

   $this->assertSame( $expected_result, $actual_result );
}

function test_is_new_and_valied_email_already_known() {
   $expected_result = false;
   $actual_result = is_new_and_valid_email( 'new@email.com', array(
      'alternate@email.com',
      'alternate1@email.com',
      'new@email.com',
   ) );

   $this->assertSame( $expected_result, $actual_result );
}

function test_is_new_and_valied_email_invalid_email() {
   $expected_result = false;
   $actual_result = is_new_and_valid_email( 'not-an-email', array() );

   $this->assertSame( $expected_result, $actual_result );
}

These tests are valid but there is a fair amount of duplication in the code. The only real differences between the three assertions are the expected result, the email we’re adding and the known list. The rest of the code is the same.

What if we have a way of passing those three items as parameters to the same test? Well we do, it’s called a DataProvider.

Option 2 : Use a DataProvider

At its base, a DataProvider is a function that returns an array consisting of the parameters for each assertion to be run:

/**
 * Example DataProvider
 */
function example_dataprovider() {
    return array(
    'param_for_test_1',
    'param_for_test_2',
    'param_for_test_3',
    );
}

In practice, DataProviders usually returns an array of values for each test simply because at the very least you will want to pass the expected result of the test and a value to pass to the code your testing.

We’ll need to refactor our test code a bit in order to use a DataProvider:

function test_is_new_and_valid_email( $expected_result, $new_email, $list_of_known_emails ) {
      $actual_result = is_new_and_valid_email( $new_email, $list_of_saved_emails );
      $this->assertSame( $expected_result, $actual_result );
}

As you can see, the testing function now accepts 3 parameters that will be passed to it from the DataProvider which looks like this:

function data_is_new_and_valid_email() {
   return array(
      // Valid email address that doesn't exist.
      array(
         true,
         'new@email.com',
         array(
            'alternate@email.com',
            'alternate2@email.com',
         ),
      ),
      // Valid email that already exists.
      array(
         false,
         'new@email.com',
         array(
            'alternate@email.com',
            'alternate1@email.com',
            'new@email.com',
         ),
      ),
      // Invalid email.
      array(
         false,
         'not-an-email',
         array(),
      ),
   );
}

** Just an aside here, the name you use for the Data Provider doesn’t matter, I tend to use the convention of using the test function name and changing test_ to data_ to make the association clear. ***

Each of the arrays being returned contains the parameters, in order, that the test function is expecting; The $expected_result , the $new_email we’re adding and the $list_of_known_emails

At this point, we have our testing function and the DataProvider ready but they don’t know about each other. Connecting them is easy, we simply a new annotation to the testing function and PHPUnit will make the connection for us:

/**
 * Simple unit test with a dataprovider so we can run many assertions in one test.
 *
 * The dataProvider annotation tells PHPUnit which function it should use
 * for the data to test.
 *
 * @dataProvider data_is_new_and_valid_email
 */
function test_is_new_and_valid_email( $expected_result, $new_email, $list_of_saved_emails ) {
   $actual_result = is_new_and_valid_email( $new_email, $list_of_saved_emails );
   $this->assertSame( $expected_result, $actual_result );
}

Now when we run our tests, the test_is_new_and_valid_email test will run for each index in the DataProvider array and will be passed their parameters. If you ever need to add another test case, it’s a simple as adding a new array to the DataProvider!

As you can see, even though there is a little more setup involved for a DataProvider, your tests become more concise and easier to maintain and extend.

Here is the final test class with some comments:

/**
 * Class Simple_Tests
 *
 * Tests that just use PHPUnit
 *
 * @group simple
 */
class Simple_Tests extends PHPUnit_Framework_TestCase {

   /**
    * Simple unit test with a dataprovider so we can run many assertions in one test.
    *
    * The dataProvider annotation tells PHPUnit which function it should use
    * for the data to test.
    *
    *
    * @param bool $expected_result
    * @param string $new_email
    * @param array|mixed $list_of_saved_emails
    *
    * @dataProvider data_is_new_and_valid_email
    */
   function test_is_new_and_valid_email( $expected_result, $new_email, $list_of_saved_emails ) {
      $actual_result = is_new_and_valid_email( $new_email, $list_of_saved_emails );
      $this->assertSame( $expected_result, $actual_result );
   }

   /**
    * Data provider.
    *
    * @return array {
    * @type array {
    * @type bool $expected_result
    * @type string $new_email
    * @type array $list_of_saved_emails
    * }
    * }
    */
   function data_is_new_and_valid_email() {
      return array(
         // Valid email address that doesn't exist.
         array(
            true,
            'new@email.com',
            array(
               'alternate@email.com',
               'alternate2@email.com',
            ),
         ),
         // Valid email that already exists.
         array(
            false,
            'new@email.com',
            array(
               'alternate@email.com',
               'alternate1@email.com',
               'new@email.com',
            ),
         ),
         // Invalid email.
         array(
            false,
            'not-an-email',
            array(),
         ),
      );
   }
}

What do you think of dataProviders? Are they useful? Please let me know in the comments!

The post Better Unit Testing with DataProviders appeared first on Ryan Welcher.