@wordpress/block-directory
Edit
Package used to extend editor with block directory features to search and install blocks.
This package is meant to be used only with WordPress core. Feel free to use it in your own project but please keep in mind that it might never get fully documented.
Installation Installation
Install the module
npm install @wordpress/block-directory --save
This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for ES2015+ such as IE browsers then using core-js will add polyfills for these methods.
Usage Usage
This package builds a standalone JS file. When loaded on a page with the block editor, it extends the block inserter to search for blocks from WordPress.org.
To do this, it uses the __unstableInserterMenuExtension
, a slot-fill area hooked into the block types list. When the user runs a search and there are no results currently installed, it fires off a request to WordPress.org for matching blocks. These are listed for the user to install with a one-click process that installs, activates, and injects the block into the post. When the post is saved, if the block was not used, it will be silently uninstalled to avoid clutter.
See also the API endpoints for searching WordPress.org: /wp/v2/block-directory/search
, and installing & activating plugins: /wp/v2/plugins/
.
Actions Actions
The following set of dispatching action creators are available on the object returned by wp.data.dispatch( 'core/block-directory' )
:
addInstalledBlockType addInstalledBlockType
Returns an action object used to add a block type to the “newly installed”
tracking list.
Parameters
- item
Object
: The block item with the block id and name.
Returns
Object
: Action object.
clearErrorNotice clearErrorNotice
Sets the error notice to empty for specific block.
Parameters
- blockId
string
: The ID of the block plugin. eg: my-block
Returns
Object
: Action object.
fetchDownloadableBlocks fetchDownloadableBlocks
Returns an action object used in signalling that the downloadable blocks
have been requested and are loading.
Parameters
- filterValue
string
: Search string.
Returns
Object
: Action object.
installBlockType installBlockType
Action triggered to install a block plugin.
Parameters
- block
Object
: The block item returned by search.
Returns
boolean
: Whether the block was successfully installed & loaded.
receiveDownloadableBlocks receiveDownloadableBlocks
Returns an action object used in signalling that the downloadable blocks
have been updated.
Parameters
- downloadableBlocks
Array
: Downloadable blocks. - filterValue
string
: Search string.
Returns
Object
: Action object.
removeInstalledBlockType removeInstalledBlockType
Returns an action object used to remove a block type from the “newly installed”
tracking list.
Parameters
- item
string
: The block item with the block id and name.
Returns
Object
: Action object.
setErrorNotice setErrorNotice
Sets an error notice to be displayed to the user for a given block.
Parameters
- blockId
string
: The ID of the block plugin. eg: my-block - message
string
: The message shown in the notice. - isFatal
boolean
: Whether the user can recover from the error.
Returns
Object
: Action object.
setIsInstalling setIsInstalling
Returns an action object used to indicate install in progress.
Parameters
- blockId
string
: - isInstalling
boolean
:
Returns
Object
: Action object.
uninstallBlockType uninstallBlockType
Action triggered to uninstall a block plugin.
Parameters
- block
Object
: The blockType object.
Selectors Selectors
The following selectors are available on the object returned by wp.data.select( 'core/block-directory' )
:
getDownloadableBlocks getDownloadableBlocks
Returns the available uninstalled blocks.
Parameters
- state
Object
: Global application state. - filterValue
string
: Search string.
Returns
Array
: Downloadable blocks.
getErrorNoticeForBlock getErrorNoticeForBlock
Returns the error notice for a given block.
Parameters
- state
Object
: Global application state. - blockId
string
: The ID of the block plugin. eg: my-block
Returns
string|boolean
: The error text, or false if no error.
getErrorNotices getErrorNotices
Returns all block error notices.
Parameters
- state
Object
: Global application state.
Returns
Object
: Object with error notices.
getInstalledBlockTypes getInstalledBlockTypes
Returns the block types that have been installed on the server in this
session.
Parameters
- state
Object
: Global application state.
Returns
Array
: Block type items
getNewBlockTypes getNewBlockTypes
Returns block types that have been installed on the server and used in the
current post.
Parameters
- state
Object
: Global application state.
Returns
Array
: Block type items.
getUnusedBlockTypes getUnusedBlockTypes
Returns the block types that have been installed on the server but are not
used in the current post.
Parameters
- state
Object
: Global application state.
Returns
Array
: Block type items.
isInstalling isInstalling
Returns true if a block plugin install is in progress.
Parameters
- state
Object
: Global application state. - blockId
string
: Id of the block.
Returns
boolean
: Whether this block is currently being installed.
isRequestingDownloadableBlocks isRequestingDownloadableBlocks
Returns true if application is requesting for downloadable blocks.
Parameters
- state
Object
: Global application state. - filterValue
string
: Search string.
Returns
boolean
: Whether a request is in progress for the blocks list.