search

evermade / wp-block-toolkit

Toolkit for developing WordPress Gutenberg blocks.
https://www.evermade.fi
GNU General Public License v3.0
9 stars 1 forks source link
gutenberg wordpress

readme

WordPress Block Toolkit

A collection of tools for WordPress Gutenberg block building.

Styles

To include the editor styles, add this to the top of your block's _editor.scss:

@import "~@evermade/wp-block-toolkit/build/index.css";

Components

InlineNotice

Compliments the base WordPress notice system by allowing you to show either warning or error level notices inside the editor.

InlineNotice example

<InlineNotice status="error">
    <strong>Error: </strong> Lorem ipsum dolor sit amet.
</InlineNotice>

PostControl

Custom ComboboxControl for selecting a single post. Takes an array of post objects and returns and id number on change.

PostControl example

<PostControl
    label="My Label"
    value={mySelectedPostId}
    posts={myPosts}
    onChange={(value) =>
        setAttributes({
            mySelectedPostId: value,
        })
    }
/>

PostSearchControl

For selecting a single post from a large pool of posts. More performant than PostControl at the cost of requiring additional user input.

As a further performance optimization, by default shows only 20 results and a "View more results" button. You can configure the number of initial results with the numOfInitialResults prop, or disable the optimization completely by setting it to -1.

PostSearchControl example

<PostSearchControl
    type="page"
    label="Choose a page"
    placeholder="Search here"
    value={mySelectedPageId}
    onChange={(value) =>
        setAttributes({
            mySelectedPageId: value,
        })
    }
    numOfInitialResults={20}
    filterResults={(results) => {
        // You can modify the search results before returning them.
        return results;
    }}
/>

RequireBlocks

Allows you to only show components if certain blocks are installed and activated in the system. If some of the blocks are missing, displays an error instead using an InlineNotice.

RequireBlocks example

<RequireBlocks blocks={["core/paragraph", "my-namespace/my-custom-block"]}>
    <h2>My title</h2>
    <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</p>
    <MyComponent />
</RequireBlocks>

SortablePostsControl

Select and sort multiple posts, with search filtering. Takes an array of post objects and returns an array of id numbers on change.

SortablePostsControl example

<SortablePostsControl
    label={"My Label"}
    posts={myPosts}
    value={mySelectedPosts}
    onChange={(value) =>
        setAttributes({
            mySelectedPosts: value,
        })
    }
/>

SortablePostSearchControl

Select and sort multiple posts, by searching from a large pool of posts. Takes an array of post ids as value and returns the same on change.

SortablePostsControl example

<SortablePostSearchControl
    type="page"
    label="Choose pages"
    placeholder="Search here"
    value={mySelectedPageIds}
    onChange={(value) =>
        setAttributes({
            mySelectedPageIds: value,
        })
    }
    numOfInitialResults={20}
    filterResults={(results) => {
        // You can modify the search results before returning them.
        return results;
    }}
/>

TaxonomyControl

Similar to the default WordPress category selector, shows a filterable list of checkboxes.

TaxonomyControl example

<TaxonomyControl
    slug="category"
    label="My Label"
    value={mySelectedTaxonomies}
    onChange={(value) => setAttributes({ mySelectedTaxonomies: value })}
/>

Hooks

useAllPosts

QoL wrapper for getting all posts of a certain post type, ordered alphabetically by title.

const stories = useAllPosts("story");
const contacts = useAllPosts("contact");

useRequiredBlocks

Checks if the listed block names are installed and activated on the site. Also returns the list of missing block names if you wish to list them in an error message for example.

const { missingBlocks, hasRequiredBlocks } = useRequiredBlocks([
    "core/paragraph",
    "core/image",
]);

usePost

QoL wrapper for getting a single post entity using a post type and id.

const story = usePost("story", 13);

usePostSearch

Similar to useAllPosts, except uses a search parameter for the query. Much more performant when dealing with large amounts of content.

It's recommended to debounce the search string, to avoid excessive database queries.

const loremIpsumStories = usePostSearch({
    postType: "story",
    search: "lorem ipsum",
});

Changelog

6.1.0

6.0.0

5.0.3

5.0.2

5.0.1

5.0.0

4.1.0

4.0.0

3.1.1

3.1.0

3.0.0

2.0.0

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

0.4.0

0.3.0

0.2.0

0.1.0

Development