diff --git a/docs/manifest.json b/docs/manifest.json index b483449872cc7..e4eba19d99fa2 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -497,6 +497,30 @@ "markdown_source": "../docs/reference-guides/interactivity-api/README.md", "parent": "reference-guides" }, + { + "title": "Core Concepts", + "slug": "core-concepts", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/README.md", + "parent": "interactivity-api" + }, + { + "title": "The Reactive and Declarative mindset", + "slug": "the-reactive-and-declarative-mindset", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md", + "parent": "core-concepts" + }, + { + "title": "Understanding global state, local context and derived state", + "slug": "undestanding-global-state-local-context-and-derived-state", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md", + "parent": "core-concepts" + }, + { + "title": "Server-side rendering: Processing directives on the server", + "slug": "server-side-rendering", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md", + "parent": "core-concepts" + }, { "title": "Quick start guide", "slug": "iapi-quick-start-guide", diff --git a/docs/reference-guides/interactivity-api/core-concepts/README.md b/docs/reference-guides/interactivity-api/core-concepts/README.md new file mode 100644 index 0000000000000..ef59fb6075f92 --- /dev/null +++ b/docs/reference-guides/interactivity-api/core-concepts/README.md @@ -0,0 +1,9 @@ +# Core Concepts + +This section provides some guides on important concepts and mental models related to Interactivity API development. Use the following links to learn more: + +1. **[The Reactive and Declarative mindset](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset):** This guide covers core concepts of reactivity and declarativeness, providing a foundation for effective use of the Interactivity API. + +2. **[Understanding global state, local context and derived state](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state):** The guide explains how to effectively use global state, local context, and derived state within the Interactivity API emphasizing the importance of choosing the appropriate state management technique based on the scope and requirements of your data. + +3. **[Server-side rendering: Processing directives on the server](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/server-side-rendering):** The Interactivity API allows WordPress to use server-side rendering to create interactive and state-aware HTML, smoothly connected with client-side features while maintaining performance and SEO benefits. diff --git a/docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md b/docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md new file mode 100644 index 0000000000000..2032d12d5670b --- /dev/null +++ b/docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md @@ -0,0 +1,491 @@ +# Server-side rendering: Processing directives on the server + +WordPress has always been built on the foundation of server-side rendering. Traditionally, when a user requests a WordPress page, the server processes the PHP code, queries the database, and generates the HTML markup that is sent to the browser. + +In recent years, modern JavaScript frameworks like Vue, React, or Svelte have revolutionized the way we build web applications. These frameworks provide reactive and declarative programming models that enable developers to create dynamic, interactive user interfaces with ease. + +However, when it comes to server-side rendering, these frameworks require a JavaScript-based server, such as NodeJS, to execute their code and generate the initial HTML. This means that PHP-based servers, like WordPress, cannot directly utilize these frameworks without sacrificing their native PHP rendering capabilities. This limitation poses a challenge for WordPress developers who want to leverage the power of reactive and declarative programming while still benefiting from WordPress's traditional server-side rendering strengths. The Interactivity API bridges this gap by bringing [reactive and declarative programming principles](./the-reactive-and-declarative-mindset.md) to WordPress without compromising its server-side rendering foundation. + +In this guide, we'll explore how the Interactivity API processes directives on the server, enabling WordPress to deliver interactive, state-aware HTML from the initial page load, while setting the stage for seamless client-side interactivity. + +## Processing the directives on the server + +The Interactivity API's Server Directive Processing capabilities enable WordPress to generate the initial HTML with the correct interactive state, providing a faster initial render. After the initial server-side render, the Interactivity API's client-side JavaScript takes over, enabling dynamic updates and interactions without requiring full page reloads. This approach combines the best of both worlds: the SEO and performance benefits of traditional WordPress server-side rendering, and the dynamic, reactive user interfaces offered by modern JavaScript frameworks. + +To understand how the Server Directive Processing works, let's start with an example where a list of fruits is rendered using the `data-wp-each` directive. + +The following are the necessary steps to ensure that the directives are correctly processed by the Server Directive Processing of the Interactivity API during the server-side rendering of WordPress. + +- **1. Mark the block as interactive** + + First, to enable the server processing of the interactive block's directives, you must add `supports.interactivity` to the `block.json`: + + ```json + { + "supports": { + "interactivity": true + } + } + ``` + +- **2. Initialize the global state or local context** + + Then, you must initialize either the global state or the local context that will be used during the server-side rendering of the page. + + If you are using global state, you must use the `wp_interactivity_state` function: + + ```php + wp_interactivity_state( 'myFruitPlugin', array( + 'fruits' => array( 'Apple', 'Banana', 'Cherry' ) + )); + ``` + + If you are using local context, the initial values are defined with the `data-wp-context` directive itself, either by: + + - Adding it directly to the HTML. + + ```html + + ``` + + - Using the `wp_interactivity_data_wp_context` helper. + + ```php + array( 'Apple', 'Banana', 'Cherry' ) ); + ?> + + + ``` + +- **3. Define the interactive elements using directives** + + Next, you need to add the necessary directives to the HTML markup. + + ```html + + ``` + + In this example: + + - The `data-wp-interactive` directive activates the interactivity for the DOM element and its children. + - The `data-wp-each` directive is used to render a list of elements. The directive can be used in `