[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> blocks.php (summary)

Functions related to registering and parsing blocks.

File Size: 2269 lines (82 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 1 file
 wp-includes/blocks/blocks-json.php

Defines 50 functions

  remove_block_asset_path_prefix()
  generate_block_asset_handle()
  get_block_asset_url()
  register_block_script_module_id()
  register_block_script_handle()
  register_block_style_handle()
  get_block_metadata_i18n_schema()
  register_block_type_from_metadata()
  register_block_type()
  unregister_block_type()
  has_blocks()
  has_block()
  get_dynamic_block_names()
  get_hooked_blocks()
  insert_hooked_blocks()
  set_ignored_hooked_blocks_metadata()
  make_before_block_visitor()
  make_after_block_visitor()
  serialize_block_attributes()
  strip_core_block_namespace()
  get_comment_delimited_block_content()
  serialize_block()
  serialize_blocks()
  traverse_and_serialize_block()
  traverse_and_serialize_blocks()
  filter_block_content()
  _filter_block_content_callback()
  filter_block_kses()
  filter_block_kses_value()
  excerpt_remove_blocks()
  excerpt_remove_footnotes()
  _excerpt_render_inner_blocks()
  render_block()
  parse_blocks()
  do_blocks()
  _restore_wpautop_hook()
  block_version()
  register_block_style()
  unregister_block_style()
  block_has_support()
  wp_migrate_old_typography_shape()
  build_query_vars_from_query_block()
  get_query_pagination_arrow()
  build_comment_query_vars_from_block()
  get_comments_pagination_arrow()
  _wp_filter_post_meta_footnotes()
  _wp_footnotes_kses_init_filters()
  _wp_footnotes_remove_filters()
  _wp_footnotes_kses_init()
  _wp_footnotes_force_filtered_html_on_import_filter()

Functions
Functions that are not part of a class:

remove_block_asset_path_prefix( $asset_handle_or_path )   X-Ref
Removes the block asset's path prefix if provided.

return: string Path without the prefix or the original value.
param: string $asset_handle_or_path Asset handle or prefixed path.

generate_block_asset_handle( $block_name, $field_name, $index = 0 )   X-Ref
Generates the name for an asset based on the name of the block
and the field name provided.

return: string Generated asset name for the block's field.
param: string $block_name Name of the block.
param: string $field_name Name of the metadata field.
param: int    $index      Optional. Index of the asset when multiple items passed.

get_block_asset_url( $path )   X-Ref
Gets the URL to a block asset.

return: string|false The URL to the block asset or false on failure.
param: string $path A normalized path to a block asset.

register_block_script_module_id( $metadata, $field_name, $index = 0 )   X-Ref
Finds a script module ID for the selected block metadata field. It detects
when a path to file was provided and optionally finds a corresponding asset
file with details necessary to register the script module under with an
automatically generated module ID. It returns unprocessed script module
ID otherwise.

return: string|false Script module ID or false on failure.
param: array  $metadata   Block metadata.
param: string $field_name Field name to pick from metadata.
param: int    $index      Optional. Index of the script module ID to register when multiple

register_block_script_handle( $metadata, $field_name, $index = 0 )   X-Ref
Finds a script handle for the selected block metadata field. It detects
when a path to file was provided and optionally finds a corresponding asset
file with details necessary to register the script under automatically
generated handle name. It returns unprocessed script handle otherwise.

return: string|false Script handle provided directly or created through
param: array  $metadata   Block metadata.
param: string $field_name Field name to pick from metadata.
param: int    $index      Optional. Index of the script to register when multiple items passed.

register_block_style_handle( $metadata, $field_name, $index = 0 )   X-Ref
Finds a style handle for the block metadata field. It detects when a path
to file was provided and registers the style under automatically
generated handle name. It returns unprocessed style handle otherwise.

return: string|false Style handle provided directly or created through
param: array  $metadata   Block metadata.
param: string $field_name Field name to pick from metadata.
param: int    $index      Optional. Index of the style to register when multiple items passed.

get_block_metadata_i18n_schema()   X-Ref
Gets i18n schema for block's metadata read from `block.json` file.

return: object The schema for block's metadata.

register_block_type_from_metadata( $file_or_folder, $args = array()   X-Ref
Registers a block type from the metadata stored in the `block.json` file.

return: WP_Block_Type|false The registered block type on success, or false on failure.
param: string $file_or_folder Path to the JSON file with metadata definition for
param: array  $args           Optional. Array of block type arguments. Accepts any public property

register_block_type( $block_type, $args = array()   X-Ref
Registers a block type. The recommended way is to register a block type using
the metadata stored in the `block.json` file.

return: WP_Block_Type|false The registered block type on success, or false on failure.
param: string|WP_Block_Type $block_type Block type name including namespace, or alternatively
param: array                $args       Optional. Array of block type arguments. Accepts any public property

unregister_block_type( $name )   X-Ref
Unregisters a block type.

return: WP_Block_Type|false The unregistered block type on success, or false on failure.
param: string|WP_Block_Type $name Block type name including namespace, or alternatively

has_blocks( $post = null )   X-Ref
Determines whether a post or content string has blocks.

This test optimizes for performance rather than strict accuracy, detecting
the pattern of a block but not validating its structure. For strict accuracy,
you should use the block parser on post content.

return: bool Whether the post has blocks.
param: int|string|WP_Post|null $post Optional. Post content, post ID, or post object.

has_block( $block_name, $post = null )   X-Ref
Determines whether a $post or a string contains a specific block type.

This test optimizes for performance rather than strict accuracy, detecting
whether the block type exists but not validating its structure and not checking
synced patterns (formerly called reusable blocks). For strict accuracy,
you should use the block parser on post content.

return: bool Whether the post content contains the specified block.
param: string                  $block_name Full block type to look for.
param: int|string|WP_Post|null $post       Optional. Post content, post ID, or post object.

get_dynamic_block_names()   X-Ref
Returns an array of the names of all registered dynamic block types.

return: string[] Array of dynamic block names.

get_hooked_blocks()   X-Ref
Retrieves block types hooked into the given block, grouped by anchor block type and the relative position.

return: array[] Array of block types grouped by anchor block type and the relative position.

insert_hooked_blocks( &$parsed_anchor_block, $relative_position, $hooked_blocks, $context )   X-Ref
Returns the markup for blocks hooked to the given anchor block in a specific relative position.

return: string
param: array                   $parsed_anchor_block The anchor block, in parsed block array format.
param: string                  $relative_position   The relative position of the hooked blocks.
param: array                   $hooked_blocks       An array of hooked block types, grouped by anchor block and relative position.
param: WP_Block_Template|array $context             The block template, template part, or pattern that the anchor block belongs to.

set_ignored_hooked_blocks_metadata( &$parsed_anchor_block, $relative_position, $hooked_blocks, $context )   X-Ref
Adds a list of hooked block types to an anchor block's ignored hooked block types.

This function is meant for internal use only.

return: string An empty string.
param: array                   $parsed_anchor_block The anchor block, in parsed block array format.
param: string                  $relative_position   The relative position of the hooked blocks.
param: array                   $hooked_blocks       An array of hooked block types, grouped by anchor block and relative position.
param: WP_Block_Template|array $context             The block template, template part, or pattern that the anchor block belongs to.

make_before_block_visitor( $hooked_blocks, $context, $callback = 'insert_hooked_blocks' )   X-Ref
Returns a function that injects the theme attribute into, and hooked blocks before, a given block.

The returned function can be used as `$pre_callback` argument to `traverse_and_serialize_block(s)`,
where it will inject the `theme` attribute into all Template Part blocks, and prepend the markup for
any blocks hooked `before` the given block and as its parent's `first_child`, respectively.

This function is meant for internal use only.

return: callable A function that returns the serialized markup for the given block,
param: array                           $hooked_blocks An array of blocks hooked to another given block.
param: WP_Block_Template|WP_Post|array $context       A block template, template part, `wp_navigation` post object,
param: callable                        $callback      A function that will be called for each block to generate

make_after_block_visitor( $hooked_blocks, $context, $callback = 'insert_hooked_blocks' )   X-Ref
Returns a function that injects the hooked blocks after a given block.

The returned function can be used as `$post_callback` argument to `traverse_and_serialize_block(s)`,
where it will append the markup for any blocks hooked `after` the given block and as its parent's
`last_child`, respectively.

This function is meant for internal use only.

return: callable A function that returns the serialized markup for the given block,
param: array                           $hooked_blocks An array of blocks hooked to another block.
param: WP_Block_Template|WP_Post|array $context       A block template, template part, `wp_navigation` post object,
param: callable                        $callback      A function that will be called for each block to generate

serialize_block_attributes( $block_attributes )   X-Ref
Given an array of attributes, returns a string in the serialized attributes
format prepared for post content.

The serialized result is a JSON-encoded string, with unicode escape sequence
substitution for characters which might otherwise interfere with embedding
the result in an HTML comment.

This function must produce output that remains in sync with the output of
the serializeAttributes JavaScript function in the block editor in order
to ensure consistent operation between PHP and JavaScript.

return: string Serialized attributes.
param: array $block_attributes Attributes object.

strip_core_block_namespace( $block_name = null )   X-Ref
Returns the block name to use for serialization. This will remove the default
"core/" namespace from a block name.

return: string Block name to use for serialization.
param: string|null $block_name Optional. Original block name. Null if the block name is unknown,

get_comment_delimited_block_content( $block_name, $block_attributes, $block_content )   X-Ref
Returns the content of a block, including comment delimiters.

return: string Comment-delimited block content.
param: string|null $block_name       Block name. Null if the block name is unknown,
param: array       $block_attributes Block attributes.
param: string      $block_content    Block save content.

serialize_block( $block )   X-Ref
Returns the content of a block, including comment delimiters, serializing all
attributes from the given parsed block.

This should be used when preparing a block to be saved to post content.
Prefer `render_block` when preparing a block for display. Unlike
`render_block`, this does not evaluate a block's `render_callback`, and will
instead preserve the markup as parsed.

return: string String of rendered HTML.
param: array $block A representative array of a single parsed block object. See WP_Block_Parser_Block.

serialize_blocks( $blocks )   X-Ref
Returns a joined string of the aggregate serialization of the given
parsed blocks.

return: string String of rendered HTML.
param: array[] $blocks An array of representative arrays of parsed block objects. See serialize_block().

traverse_and_serialize_block( $block, $pre_callback = null, $post_callback = null )   X-Ref
Traverses a parsed block tree and applies callbacks before and after serializing it.

Recursively traverses the block and its inner blocks and applies the two callbacks provided as
arguments, the first one before serializing the block, and the second one after serializing it.
If either callback returns a string value, it will be prepended and appended to the serialized
block markup, respectively.

The callbacks will receive a reference to the current block as their first argument, so that they
can also modify it, and the current block's parent block as second argument. Finally, the
`$pre_callback` receives the previous block, whereas the `$post_callback` receives
the next block as third argument.

Serialized blocks are returned including comment delimiters, and with all attributes serialized.

This function should be used when there is a need to modify the saved block, or to inject markup
into the return value. Prefer `serialize_block` when preparing a block to be saved to post content.

This function is meant for internal use only.

return: string Serialized block markup.
param: array    $block         A representative array of a single parsed block object. See WP_Block_Parser_Block.
param: callable $pre_callback  Callback to run on each block in the tree before it is traversed and serialized.
param: callable $post_callback Callback to run on each block in the tree after it is traversed and serialized.

traverse_and_serialize_blocks( $blocks, $pre_callback = null, $post_callback = null )   X-Ref
Given an array of parsed block trees, applies callbacks before and after serializing them and
returns their concatenated output.

Recursively traverses the blocks and their inner blocks and applies the two callbacks provided as
arguments, the first one before serializing a block, and the second one after serializing.
If either callback returns a string value, it will be prepended and appended to the serialized
block markup, respectively.

The callbacks will receive a reference to the current block as their first argument, so that they
can also modify it, and the current block's parent block as second argument. Finally, the
`$pre_callback` receives the previous block, whereas the `$post_callback` receives
the next block as third argument.

Serialized blocks are returned including comment delimiters, and with all attributes serialized.

This function should be used when there is a need to modify the saved blocks, or to inject markup
into the return value. Prefer `serialize_blocks` when preparing blocks to be saved to post content.

This function is meant for internal use only.

return: string Serialized block markup.
param: array[]  $blocks        An array of parsed blocks. See WP_Block_Parser_Block.
param: callable $pre_callback  Callback to run on each block in the tree before it is traversed and serialized.
param: callable $post_callback Callback to run on each block in the tree after it is traversed and serialized.

filter_block_content( $text, $allowed_html = 'post', $allowed_protocols = array()   X-Ref
Filters and sanitizes block content to remove non-allowable HTML
from parsed block attribute values.

return: string The filtered and sanitized content result.
param: string         $text              Text that may contain block content.
param: array[]|string $allowed_html      Optional. An array of allowed HTML elements and attributes,
param: string[]       $allowed_protocols Optional. Array of allowed URL protocols.

_filter_block_content_callback( $matches )   X-Ref
Callback used for regular expression replacement in filter_block_content().

return: string Replacement string.
param: array $matches Array of preg_replace_callback matches.

filter_block_kses( $block, $allowed_html, $allowed_protocols = array()   X-Ref
Filters and sanitizes a parsed block to remove non-allowable HTML
from block attribute values.

return: array The filtered and sanitized block object result.
param: WP_Block_Parser_Block $block             The parsed block object.
param: array[]|string        $allowed_html      An array of allowed HTML elements and attributes,
param: string[]              $allowed_protocols Optional. Array of allowed URL protocols.

filter_block_kses_value( $value, $allowed_html, $allowed_protocols = array()   X-Ref
Filters and sanitizes a parsed block attribute value to remove
non-allowable HTML.

return: string[]|string The filtered and sanitized result.
param: string[]|string $value             The attribute value to filter.
param: array[]|string  $allowed_html      An array of allowed HTML elements and attributes,
param: string[]        $allowed_protocols Optional. Array of allowed URL protocols.

excerpt_remove_blocks( $content )   X-Ref
Parses blocks out of a content string, and renders those appropriate for the excerpt.

As the excerpt should be a small string of text relevant to the full post content,
this function renders the blocks that are most likely to contain such text.

return: string The parsed and filtered content.
param: string $content The content to parse.

excerpt_remove_footnotes( $content )   X-Ref
Parses footnotes markup out of a content string,
and renders those appropriate for the excerpt.

return: string The parsed and filtered content.
param: string $content The content to parse.

_excerpt_render_inner_blocks( $parsed_block, $allowed_blocks )   X-Ref
Renders inner blocks from the allowed wrapper blocks
for generating an excerpt.

return: string The rendered inner blocks.
param: array $parsed_block   The parsed block.
param: array $allowed_blocks The list of allowed inner blocks.

render_block( $parsed_block )   X-Ref
Renders a single block into a HTML string.

return: string String of rendered HTML.
param: array $parsed_block A single parsed block object.

parse_blocks( $content )   X-Ref
Parses blocks out of a content string.

return: array[] Array of parsed block objects.
param: string $content Post content.

do_blocks( $content )   X-Ref
Parses dynamic blocks out of `post_content` and re-renders them.

return: string Updated post content.
param: string $content Post content.

_restore_wpautop_hook( $content )   X-Ref
If do_blocks() needs to remove wpautop() from the `the_content` filter, this re-adds it afterwards,
for subsequent `the_content` usage.

return: string The unmodified content.
param: string $content The post content running through this filter.

block_version( $content )   X-Ref
Returns the current version of the block format that the content string is using.

If the string doesn't contain blocks, it returns 0.

return: int The block format version is 1 if the content contains one or more blocks, 0 otherwise.
param: string $content Content to test.

register_block_style( $block_name, $style_properties )   X-Ref
Registers a new block style.

return: bool True if the block style was registered with success and false otherwise.
param: string $block_name       Block type name including namespace.
param: array  $style_properties Array containing the properties of the style name, label,

unregister_block_style( $block_name, $block_style_name )   X-Ref
Unregisters a block style.

return: bool True if the block style was unregistered with success and false otherwise.
param: string $block_name       Block type name including namespace.
param: string $block_style_name Block style name.

block_has_support( $block_type, $feature, $default_value = false )   X-Ref
Checks whether the current block type supports the feature requested.

return: bool Whether the feature is supported.
param: WP_Block_Type $block_type    Block type to check for support.
param: string|array  $feature       Feature slug, or path to a specific feature to check support for.
param: mixed         $default_value Optional. Fallback value for feature support. Default false.

wp_migrate_old_typography_shape( $metadata )   X-Ref
Converts typography keys declared under `supports.*` to `supports.typography.*`.

Displays a `_doing_it_wrong()` notice when a block using the older format is detected.

return: array Filtered metadata for registering a block type.
param: array $metadata Metadata for registering a block type.

build_query_vars_from_query_block( $block, $page )   X-Ref
Helper function that constructs a WP_Query args array from
a `Query` block properties.

It's used in Query Loop, Query Pagination Numbers and Query Pagination Next blocks.

return: array Returns the constructed WP_Query arguments.
param: WP_Block $block Block instance.
param: int      $page  Current query's page.

get_query_pagination_arrow( $block, $is_next )   X-Ref
Helper function that returns the proper pagination arrow HTML for
`QueryPaginationNext` and `QueryPaginationPrevious` blocks based
on the provided `paginationArrow` from `QueryPagination` context.

It's used in QueryPaginationNext and QueryPaginationPrevious blocks.

return: string|null The pagination arrow HTML or null if there is none.
param: WP_Block $block   Block instance.
param: bool     $is_next Flag for handling `next/previous` blocks.

build_comment_query_vars_from_block( $block )   X-Ref
Helper function that constructs a comment query vars array from the passed
block properties.

It's used with the Comment Query Loop inner blocks.

return: array Returns the comment query parameters to use with the
param: WP_Block $block Block instance.

get_comments_pagination_arrow( $block, $pagination_type = 'next' )   X-Ref
Helper function that returns the proper pagination arrow HTML for
`CommentsPaginationNext` and `CommentsPaginationPrevious` blocks based on the
provided `paginationArrow` from `CommentsPagination` context.

It's used in CommentsPaginationNext and CommentsPaginationPrevious blocks.

return: string|null The pagination arrow HTML or null if there is none.
param: WP_Block $block           Block instance.
param: string   $pagination_type Optional. Type of the arrow we will be rendering.

_wp_filter_post_meta_footnotes( $footnotes )   X-Ref
Strips all HTML from the content of footnotes, and sanitizes the ID.

This function expects slashed data on the footnotes content.

return: string Filtered content without any HTML on the footnote content and with the sanitized ID.
param: string $footnotes JSON-encoded string of an array containing the content and ID of each footnote.

_wp_footnotes_kses_init_filters()   X-Ref
Adds the filters for footnotes meta field.


_wp_footnotes_remove_filters()   X-Ref
Removes the filters for footnotes meta field.


_wp_footnotes_kses_init()   X-Ref
Registers the filter of footnotes meta field if the user does not have `unfiltered_html` capability.


_wp_footnotes_force_filtered_html_on_import_filter( $arg )   X-Ref
Initializes the filters for footnotes meta field when imported data should be filtered.

This filter is the last one being executed on {@see 'force_filtered_html_on_import'}.
If the input of the filter is true, it means we are in an import situation and should
enable kses, independently of the user capabilities. So in that case we call
_wp_footnotes_kses_init_filters().

return: string Input argument of the filter.
param: string $arg Input argument of the filter.



Generated : Thu Apr 18 08:20:02 2024 Cross-referenced by PHPXref