[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   * Retrieves the main WP_Interactivity_API instance.
  12   *
  13   * It provides access to the WP_Interactivity_API instance, creating one if it
  14   * doesn't exist yet.
  15   *
  16   * @since 6.5.0
  17   *
  18   * @global WP_Interactivity_API $wp_interactivity
  19   *
  20   * @return WP_Interactivity_API The main WP_Interactivity_API instance.
  21   */
  22  function wp_interactivity(): WP_Interactivity_API {
  23      global $wp_interactivity;
  24      if ( ! ( $wp_interactivity instanceof WP_Interactivity_API ) ) {
  25          $wp_interactivity = new WP_Interactivity_API();
  26      }
  27      return $wp_interactivity;
  28  }
  29  
  30  /**
  31   * Processes the interactivity directives contained within the HTML content
  32   * and updates the markup accordingly.
  33   *
  34   * @since 6.5.0
  35   *
  36   * @param string $html The HTML content to process.
  37   * @return string The processed HTML content. It returns the original content when the HTML contains unbalanced tags.
  38   */
  39  function wp_interactivity_process_directives( string $html ): string {
  40      return wp_interactivity()->process_directives( $html );
  41  }
  42  
  43  /**
  44   * Gets and/or sets the initial state of an Interactivity API store for a
  45   * given namespace.
  46   *
  47   * If state for that store namespace already exists, it merges the new
  48   * provided state with the existing one.
  49   *
  50   * The namespace can be omitted inside derived state getters, using the
  51   * namespace where the getter is defined.
  52   *
  53   * @since 6.5.0
  54   * @since 6.6.0 The namespace can be omitted when called inside derived state getters.
  55   *
  56   * @param string $store_namespace The unique store namespace identifier.
  57   * @param array  $state           Optional. The array that will be merged with the existing state for the specified
  58   *                                store namespace.
  59   * @return array The state for the specified store namespace. This will be the updated state if a $state argument was
  60   *               provided.
  61   */
  62  function wp_interactivity_state( ?string $store_namespace = null, array $state = array() ): array {
  63      return wp_interactivity()->state( $store_namespace, $state );
  64  }
  65  
  66  /**
  67   * Gets and/or sets the configuration of the Interactivity API for a given
  68   * store namespace.
  69   *
  70   * If configuration for that store namespace exists, it merges the new
  71   * provided configuration with the existing one.
  72   *
  73   * @since 6.5.0
  74   *
  75   * @param string $store_namespace The unique store namespace identifier.
  76   * @param array  $config          Optional. The array that will be merged with the existing configuration for the
  77   *                                specified store namespace.
  78   * @return array The configuration for the specified store namespace. This will be the updated configuration if a
  79   *               $config argument was provided.
  80   */
  81  function wp_interactivity_config( string $store_namespace, array $config = array() ): array {
  82      return wp_interactivity()->config( $store_namespace, $config );
  83  }
  84  
  85  /**
  86   * Generates a `data-wp-context` directive attribute by encoding a context
  87   * array.
  88   *
  89   * This helper function simplifies the creation of `data-wp-context` directives
  90   * by providing a way to pass an array of data, which encodes into a JSON string
  91   * safe for direct use as a HTML attribute value.
  92   *
  93   * Example:
  94   *
  95   *     <div <?php echo wp_interactivity_data_wp_context( array( 'isOpen' => true, 'count' => 0 ) ); ?>>
  96   *
  97   * @since 6.5.0
  98   *
  99   * @param array  $context         The array of context data to encode.
 100   * @param string $store_namespace Optional. The unique store namespace identifier.
 101   * @return string A complete `data-wp-context` directive with a JSON encoded value representing the context array and
 102   *                the store namespace if specified.
 103   */
 104  function wp_interactivity_data_wp_context( array $context, string $store_namespace = '' ): string {
 105      return 'data-wp-context=\'' .
 106          ( $store_namespace ? $store_namespace . '::' : '' ) .
 107          ( empty( $context ) ? '{}' : wp_json_encode( $context, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP ) ) .
 108          '\'';
 109  }
 110  
 111  /**
 112   * Gets the current Interactivity API context for a given namespace.
 113   *
 114   * The function should be used only during directive processing. If the
 115   * `$store_namespace` parameter is omitted, it uses the current namespace value
 116   * on the internal namespace stack.
 117   *
 118   * It returns an empty array when the specified namespace is not defined.
 119   *
 120   * @since 6.6.0
 121   *
 122   * @param string $store_namespace Optional. The unique store namespace identifier.
 123   * @return array The context for the specified store namespace.
 124   */
 125  function wp_interactivity_get_context( ?string $store_namespace = null ): array {
 126      return wp_interactivity()->get_context( $store_namespace );
 127  }
 128  
 129  /**
 130   * Returns an array representation of the current element being processed.
 131   *
 132   * The function should be used only during directive processing.
 133   *
 134   * @since 6.7.0
 135   *
 136   * @return array{attributes: array<string, string|bool>}|null Current element.
 137   */
 138  function wp_interactivity_get_element(): ?array {
 139      return wp_interactivity()->get_element();
 140  }