Skip to content

Commit

Permalink
Refine getServerState() & getServerContext() docs (#67499)
Browse files Browse the repository at this point in the history
* `getServerState()` & `getServerContext()` docs: Add note about reactivity.

* Fix the code snippets

* Add note about local context

* Fix param order and function name

* Remove the namespace and use the correct functions

Co-authored-by: michalczaplinski <czapla@git.wordpress.org>
Co-authored-by: luisherranz <luisherranz@git.wordpress.org>
  • Loading branch information
3 people committed Dec 5, 2024
1 parent 473e858 commit 5a242b5
Showing 1 changed file with 10 additions and 10 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -745,15 +745,15 @@ When using region-based navigation, it's crucial to ensure that your interactive

`getServerState()` allows you to subscribe to changes in the **global state** that occur during client-side navigation. This function is analogous to `getServerContext()`, but it works with the global state instead of the local context.

The `getServerState()` function returns a read-only reactive object. This means that any [callbacks](/docs/reference-guides/interactivity-api/api-reference.md#accessing-data-in-callbacks) you have defined that watch the returned object will only trigger when the value returned by the function changes. If the value remains the same, the callback will not re-trigger.

Let's consider a quiz that has multiple questions. Each question is a separate page. When the user navigates to a new question, the server provides the new question and the time left to answer all the questions.

```php
<?php
wp_interactivity_state( 'myPlugin', array(
<div <?php echo wp_interactivity_state( 'myPlugin', array(
'question' => get_question_for_page( get_the_ID() ),
'timeLeft' => 5 * 60, // Time to answer all the questions.
) );
?>
) ); ?>>
```

```javascript
Expand Down Expand Up @@ -789,14 +789,14 @@ store( 'myPlugin', {

`getServerContext()` allows you to subscribe to changes in the **local context** that occur during client-side navigation. This function is analogous to `getServerState()`, but it works with the local context instead of the global state.

The `getServerContext()` function returns a read-only reactive object. This means that any [callbacks](/docs/reference-guides/interactivity-api/api-reference.md#accessing-data-in-callbacks) you have defined that watch the returned object will only trigger when the value returned by the function changes. If the value remains the same, the callback will not re-trigger.

Consider a quiz that has multiple questions. Each question is a separate page. When the user navigates to a new question, the server provides the new question and the time left to answer all the questions.

```php
<?php
wp_interactivity_context( 'myPlugin', array(
<div <?php echo wp_interactivity_data_wp_context( array(
'currentQuestion' => get_question_for_page( get_the_ID() ),
) );
?>
), ); ?>>
```

```javascript
Expand Down Expand Up @@ -830,12 +830,12 @@ store( 'myPlugin', {

### When to Use

Whenever you have interactive blocks that rely on global state that may change due to navigation events, ensuring consistency across different parts of your application.
Whenever you have interactive blocks that rely on global state or local context that may change due to navigation events, ensuring consistency across different parts of your application.

### Best Practices for using `getServerState()` and `getServerContext()`

- **Read-Only References:** Both `getServerState()` and `getServerContext()` return read-only objects. You can use those objects to update the global state or local context.
- **Callback Integration:** Incorporate these functions within your store [callbacks](/docs/reference-guides/interactivity-api/api-reference.md#accessing-data-in-callbacks) to react to state and context changes.
- **Callback Integration:** Incorporate these functions within your store [callbacks](/docs/reference-guides/interactivity-api/api-reference.md#accessing-data-in-callbacks) to react to state and context changes. Both `getServerState()` and `getServerContext()` return reactive objects. This means that their watch callbacks will only trigger when the value of a property changes. If the value remains the same, the callback will not re-trigger.

## Conclusion

Expand Down

0 comments on commit 5a242b5

Please sign in to comment.