@wordpress/block-library/README.md

Block library for the WordPress editor.

# Block library

Block library for the WordPress editor.

## Installation

Install the module

```bash
npm install @wordpress/block-library --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 such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._

## API

<!-- START TOKEN(Autogenerated API docs) -->

### registerCoreBlocks

Function to register core blocks provided by the block editor.

_Usage_

```js
import { registerCoreBlocks } from '@wordpress/block-library';

registerCoreBlocks();
```

_Parameters_

-   _blocks_ `Array`: An optional array of the core blocks being registered.

<!-- END TOKEN(Autogenerated API docs) -->

## Registering individual blocks

1.  When you only care about registering the block when file gets imported:

    ```js
    import '@wordpress/block-library/build-module/verse/init';
    ```

2.  When you want to use the reference to the block after it gets automatically registered:

    ```js
    import verseBlock from '@wordpress/block-library/build-module/verse/init';
    ```

3.  When you need a full control over when the block gets registered:

    ```js
    import { init } from '@wordpress/block-library/build-module/verse';

    const verseBlock = init();
    ```

## Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

### Adding new blocks

⚠️ Adding new blocks to this package **requires** additional steps!

1.  Do not forget to register a new core block in the [`index.js`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/index.js) file of this package. For example, if you were to add the new core block called `core/blinking-paragraph`, you would have to add something like:

    ```js
    // packages/block-library/src/index.js
    import * as blinkingParagraph from './blinking-paragraph';
    ```

    Then add `blinkingParagraph` to the list in the `getAllBlocks()` function.

    If it's experimental, add the following property to `block.json`:

    ```json
    {
    	"__experimental": "true"
    }
    ```

2.  Register the block in the `gutenberg_reregister_core_block_types()` function of the [`lib/blocks.php`](https://github.com/WordPress/gutenberg/blob/trunk/lib/blocks.php) file. Add it to the `block_folders` array if it's a [static block](https://developer.wordpress.org/block-editor/getting-started/glossary/#static-block) or to the `block_names` array if it's a [dynamic block](https://developer.wordpress.org/block-editor/getting-started/glossary/#dynamic-block).

3.  Add `init.js` file to the directory of the new block:

    ```js
    /**
     * Internal dependencies
     */
    import { init } from './';

    export default init();
    ```

    This file is used when using the option to register individual block from the `@wordpress/block-library` package.

4.  If the block exposes a script module on the front end, it must be included in the package's `package.json` file in the `wpScriptModules` object. This will include the script module when it's bundled for use in WordPress. See [the packages README for more details.](../README.md):

    ```json
    {
    	"name": "@wordpress/block-library",
    	"wpScriptModuleExports": {
    		"./blinking-paragraph/view": "./build-module/blinking-paragraph/view.js",
    		"./image/view": "./build-module/image/view.js"
    		// Add any new script modules here.
    	}
    }
    ```

    For every dynamic block, you need to manually enqueue the view script module in `render_callback` of the block, example:

    ```php
    function render_block_core_blinking_paragraph( $attributes, $content ) {
        $should_load_view_script = ! empty( $attributes['isInteractive'] );
        if ( $should_load_view_script ) {
    	    wp_enqueue_script_module( '@wordpress/block-library/blinking-paragraph' );
        }

    	return $content;
    }
    ```

### Naming convention for PHP functions

All PHP function names declared within the subdirectories of the `packages/block-library/src/` directory should start with one of the following prefixes:

-   `block_core_<directory_name>`
-   `render_block_core_<directory_name>`
-   `register_block_core_<directory_name>`

In this context, `<directory_name>` represents the name of the directory where the corresponding `.php` file is located.
The directory name is converted to lowercase, and any characters except for letters and digits are replaced with underscores.

#### Example:

For the PHP functions declared in the `packages/block-library/src/my-block/index.php` file, the correct prefixes would be:

-   `block_core_my_block`
-   `render_block_core_my_block`
-   `register_block_core_my_block`

#### Using plugin-specific prefixes/suffixes

Unlike in [PHP code in the /lib directory](https://github.com/WordPress/gutenberg/blob/trunk/lib/README.md), you should generally avoid applying plugin-specific prefixes/suffixes such as `gutenberg_` to functions and other code in block PHP files.

There are times, however, when blocks may need to use Gutenberg functions even when a Core-equivalent exists, for example, where a Gutenberg function relies on code that is only available in the plugin.

In such cases, you can use the corresponding Core `wp_` function in the block PHP code, and add its name to [a list of prefixed functions in the Webpack configuration file](https://github.com/WordPress/gutenberg/blob/trunk/tools/webpack/blocks.js#L30).

At build time, Webpack will search for `wp_` functions in that list and replace them with their `gutenberg_` equivalents. This process ensures that the plugin calls the `gutenberg_` functions, but the block will still call the Core `wp_` function when updates are back ported.

Webpack assumes that, prefixes aside, the functions' names are identical: `wp_get_something_useful()` will be replaced with `gutenberg_get_something_useful()`.

<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>