[wp-trac] [WordPress Trac] #60356: Interactivity API: Server Directive Processing

[WordPress Trac]

#60356: Interactivity API: Server Directive Processing
-------------------------+-----------------------------
 Reporter:  luisherranz  |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  General      |    Version:
 Severity:  normal       |   Keywords:
  Focuses:               |
-------------------------+-----------------------------
 The Interactivity API enables WordPress developers to create dynamic and
 interactive web experiences with ease using a set of special HTML
 attributes called directives. Please refer to
 [https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-
 api-a-better-developer-experience-in-building-interactive-blocks/ the
 Interactivity API proposal] for further details.

 This API processes the interactivity directives embedded within HTML
 content and transforms the markup in the server, seamlessly merging the
 server-rendered markup with the client-side interactivity to guarantee
 that:

 - Users view the correct HTML before the JavaScript loads.
 - There are no layout shifts when the JavaScript finally loads.

 == API

 === `wp_interactivity_state( $store_namespace, $state )`

 Sets or gets the initial state of an interactivity store.

 This state is used during the server directive processing and then is
 serialized and sent to the client as part of the interactivity data to be
 recovered during the hydration of the client interactivity stores.

 Once the user starts interacting with the page, the actions contained in
 the stores will update this `state`, and the Interactivity API runtime
 will transform the markup accordingly.


 {{{#!php
 <?php
 // Sets the initial state for the 'myPlugin' namespace.
 wp_interactivity_state( 'myPlugin', array( 'counter' => 0 ) );

 // Gets the current state for the 'myPlugin' namespace.
 $state = wp_interactivity_state( 'myPlugin' );
 }}}


 === `wp_interactivity_config( $store_namespace, $config )`

 Sets or gets configuration for an interactivity store.

 This configuration is also serialized to the client, but it's static
 information about the page/site (it's not reactive).

 {{{#!php
 <?php
 // Sets configuration for the  'myPlugin' namespace.
 wp_interactivity_config( 'myPlugin', array( 'setting' => true ) );

 // Gets the current configuration for the 'myPlugin' namespace.
 $config = wp_interactivity_config( 'myPlugin' );
 }}}

 === `wp_interactivity_process_directives( $html )`

 Processes directives within HTML content, updating the markup where
 necessary.

 {{{#!php
 <?php
 $html_content = '<div data-wp-bind--
 text="myPlugin::state.message"></div>';

 // Process directives in HTML content.
 wp_interactivity_state( 'myPlugin', array( 'message' => 'hello world!' )
 );
 $processed_html = wp_interactivity_process_directives( $html_content );

 // output: <div data-wp-bind--text="myPlugin::state.message">hello
 world!</div>
 }}}

 === Filter: `wp_interactivity_process_directives_of_interactive_blocks`

 This function hooks into WordPress's block rendering pipeline, identifying
 the outermost interactive block in a hierarchy and marking it for
 directive processing after rendering. Subsequent nested blocks are ignored
 during this pass because their output is included in the root block's
 render. Once the root block's HTML is processed, the markup is transformed
 and ready to be sent to the client.

 == Feedback

 Please share your thoughts, potential use cases, or any other input that
 could help us refine and enhance this feature. Use this Trac ticket or the
 main pull request for discussions.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/60356>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform