[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Interactivity API: Functions and hooks
   4   *
   5   * @package WordPress
   6   * @subpackage Interactivity API
   7   * @since 6.5.0
   8   */
   9  
  10  /**
  11   * Processes the directives on the rendered HTML of the interactive blocks.
  12   *
  13   * This processes only one root interactive block at a time because the
  14   * rendered HTML of that block contains the rendered HTML of all its inner
  15   * blocks, including any interactive block. It does so by ignoring all the
  16   * interactive inner blocks until the root interactive block is processed.
  17   *
  18   * @since 6.5.0
  19   *
  20   * @param array $parsed_block The parsed block.
  21   * @return array The same parsed block.
  22   */
  23  function wp_interactivity_process_directives_of_interactive_blocks( array $parsed_block ): array {
  24      static $root_interactive_block = null;
  25  
  26      /*
  27       * Checks whether a root interactive block is already annotated for
  28       * processing, and if it is, it ignores the subsequent ones.
  29       */
  30      if ( null === $root_interactive_block ) {
  31          $block_name = $parsed_block['blockName'];
  32          $block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block_name );
  33  
  34          if (
  35              isset( $block_name ) &&
  36              ( ( isset( $block_type->supports['interactivity'] ) && true === $block_type->supports['interactivity'] ) ||
  37              ( isset( $block_type->supports['interactivity']['interactive'] ) && true === $block_type->supports['interactivity']['interactive'] ) )
  38          ) {
  39              // Annotates the root interactive block for processing.
  40              $root_interactive_block = array( $block_name, $parsed_block );
  41  
  42              /*
  43               * Adds a filter to process the root interactive block once it has
  44               * finished rendering.
  45               */
  46              $process_interactive_blocks = static function ( string $content, array $parsed_block ) use ( &$root_interactive_block, &$process_interactive_blocks ): string {
  47                  // Checks whether the current block is the root interactive block.
  48                  list($root_block_name, $root_parsed_block) = $root_interactive_block;
  49                  if ( $root_block_name === $parsed_block['blockName'] && $parsed_block === $root_parsed_block ) {
  50                      // The root interactive blocks has finished rendering, process it.
  51                      $content = wp_interactivity_process_directives( $content );
  52                      // Removes the filter and reset the root interactive block.
  53                      remove_filter( 'render_block_' . $parsed_block['blockName'], $process_interactive_blocks );
  54                      $root_interactive_block = null;
  55                  }
  56                  return $content;
  57              };
  58  
  59              /*
  60               * Uses a priority of 100 to ensure that other filters can add additional
  61               * directives before the processing starts.
  62               */
  63              add_filter( 'render_block_' . $block_name, $process_interactive_blocks, 100, 2 );
  64          }
  65      }
  66  
  67      return $parsed_block;
  68  }
  69  /*
  70   * Uses a priority of 100 to ensure that other filters can add additional attributes to
  71   * $parsed_block before the processing starts.
  72   */
  73  add_filter( 'render_block_data', 'wp_interactivity_process_directives_of_interactive_blocks', 100, 1 );
  74  
  75  /**
  76   * Retrieves the main WP_Interactivity_API instance.
  77   *
  78   * It provides access to the WP_Interactivity_API instance, creating one if it
  79   * doesn't exist yet.
  80   *
  81   * @since 6.5.0
  82   *
  83   * @global WP_Interactivity_API $wp_interactivity
  84   *
  85   * @return WP_Interactivity_API The main WP_Interactivity_API instance.
  86   */
  87  function wp_interactivity(): WP_Interactivity_API {
  88      global $wp_interactivity;
  89      if ( ! ( $wp_interactivity instanceof WP_Interactivity_API ) ) {
  90          $wp_interactivity = new WP_Interactivity_API();
  91      }
  92      return $wp_interactivity;
  93  }
  94  
  95  /**
  96   * Processes the interactivity directives contained within the HTML content
  97   * and updates the markup accordingly.
  98   *
  99   * @since 6.5.0
 100   *
 101   * @param string $html The HTML content to process.
 102   * @return string The processed HTML content. It returns the original content when the HTML contains unbalanced tags.
 103   */
 104  function wp_interactivity_process_directives( string $html ): string {
 105      return wp_interactivity()->process_directives( $html );
 106  }
 107  
 108  /**
 109   * Gets and/or sets the initial state of an Interactivity API store for a
 110   * given namespace.
 111   *
 112   * If state for that store namespace already exists, it merges the new
 113   * provided state with the existing one.
 114   *
 115   * @since 6.5.0
 116   *
 117   * @param string $store_namespace The unique store namespace identifier.
 118   * @param array  $state           Optional. The array that will be merged with the existing state for the specified
 119   *                                store namespace.
 120   * @return array The state for the specified store namespace. This will be the updated state if a $state argument was
 121   *               provided.
 122   */
 123  function wp_interactivity_state( string $store_namespace, array $state = array() ): array {
 124      return wp_interactivity()->state( $store_namespace, $state );
 125  }
 126  
 127  /**
 128   * Gets and/or sets the configuration of the Interactivity API for a given
 129   * store namespace.
 130   *
 131   * If configuration for that store namespace exists, it merges the new
 132   * provided configuration with the existing one.
 133   *
 134   * @since 6.5.0
 135   *
 136   * @param string $store_namespace The unique store namespace identifier.
 137   * @param array  $config          Optional. The array that will be merged with the existing configuration for the
 138   *                                specified store namespace.
 139   * @return array The configuration for the specified store namespace. This will be the updated configuration if a
 140   *               $config argument was provided.
 141   */
 142  function wp_interactivity_config( string $store_namespace, array $config = array() ): array {
 143      return wp_interactivity()->config( $store_namespace, $config );
 144  }
 145  
 146  /**
 147   * Generates a `data-wp-context` directive attribute by encoding a context
 148   * array.
 149   *
 150   * This helper function simplifies the creation of `data-wp-context` directives
 151   * by providing a way to pass an array of data, which encodes into a JSON string
 152   * safe for direct use as a HTML attribute value.
 153   *
 154   * Example:
 155   *
 156   *     <div <?php echo wp_interactivity_data_wp_context( array( 'isOpen' => true, 'count' => 0 ) ); ?>>
 157   *
 158   * @since 6.5.0
 159   *
 160   * @param array  $context         The array of context data to encode.
 161   * @param string $store_namespace Optional. The unique store namespace identifier.
 162   * @return string A complete `data-wp-context` directive with a JSON encoded value representing the context array and
 163   *                the store namespace if specified.
 164   */
 165  function wp_interactivity_data_wp_context( array $context, string $store_namespace = '' ): string {
 166      return 'data-wp-context=\'' .
 167          ( $store_namespace ? $store_namespace . '::' : '' ) .
 168          ( empty( $context ) ? '{}' : wp_json_encode( $context, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP ) ) .
 169          '\'';
 170  }