Seeking clarity and more understanding of the Interactive API

[eirichmond]

Forgive me, as I'm not a fully seasoned React developer, but I know enough to figure my way around it. I say this because my terminology might be out of context, which is why I'm seeking clarity.

So, my current rudimentary understanding is that the Interactivity API is a DOM layer for HTML that we would traditionally use vanilla JavaScript for - adding data binding, appending classes, showing/hiding, and general user interactivity with HTML elements. Although it might be used to assist with things like fetch, AJAX, or external API calls, it's not directly meant for that. Its purpose is literally in-browser HTML interactivity and local WP data. Is my understanding correct?

Also, if I were looking to use the core example of using AJAX, which is currently documented in the handbook using jQuery, would I simply add my logic to the view.js file when posting to my action, although I'm not sure how that would work given the dependencies required for using jQuery? Or would I still enqueue and localize scripts separately, then use vanilla JavaScript to add event listeners, in combination of using the Interactive API etc.?

I hope I'm making sense here, but do feel free to ask if I need to explain with more clarity.

[luisherranz]

The closest mental model is to think about the Interactivity API as a (P)React application instead of as vanilla JS or jQuery.

For example, you should never mutate the DOM directly in React:

const Button = () => {
  const ref = useRef();

  const addClass = () => {
    ref.classList.add("some-class");
  };

  return <button onClick={addClass}>Add class</button>;
};

Instead of that, you should create a state that you can manipulate, and then use the existing primitives to link the DOM to that state.

const Button = () => {
  const [hasSomeClass, setHasSomeClass] = useState(false);

  const addClass = () => {
    setHasSomeClass(true);
  };

  return (
    <button className={hasSomeClass ? "some-class" : ""} onClick={addClass}>
      Add class
    </button>
  );
};

Similarly, when using the Interactivity API, you should never mutate the DOM directly:

<button data-wp-on--click="actions.addClass">Add class</button>

store("myPlugin", {
  actions: {
    addClass() {
      const { ref } = getElement();
      ref.classList.add("some-class");
    },
  },
});

Instead, you should create a state and link the class name to the state.

<button
  data-wp-class--some-class="state.hasSomeClass"
  data-wp-on--click="actions.addClass"
>
  Add class
</button>

const { state } = store("myPlugin", {
  state: {
    hasSomeClass: false,
  },
  actions: {
    addClass() {
      state.hasSomeClass = true;
    },
  },
});

That declarative approach might seem slightly more complex for very simple things like this, but it gets much much simpler when the UI starts getting complex.

I'm not sure how that would work given the dependencies required for using jQuery?

You should avoid using jQuery in conjunction with the Interactivity API, in the same way that nobody uses jQuery in conjunction with (P)React.

Can you provide the link to the documentation page you mentioned? It's probably worth updating it as nowadays, jQuery is not recommended anymore.

use vanilla JavaScript to add event listeners

As I said, you should never manipulate the DOM directly. Always use the provided event listeners instead (data-wp-on, data-wp-on-window, data-wp-on-document).

would I still enqueue and localize scripts separately

For localization, there's a simpler way: you can store the translated strings in the state, using wp_interactivity_state. The state declared in the server is serialized and available in the client as well.

<?php
$add_class_text = __( 'Add class' );
$remove_class_text = __( 'Remove class' );

wp_interactivity_state( "myPlugin", array(
  'hasSomeClass': false,
  'addClassText': $add_class_text,
  'removeClassText': $remove_class_text,
  'buttonText': $add_class_text, // initial value
));
?>

<div data-wp-interactive="myPlugin">
  <button
    data-wp-class--some-class="state.hasSomeClass"
    data-wp-on--click="actions.toggleClass"
    data-wp-text="state.buttonText"
  ></button>
</div>

const { state } = store("myPlugin", {
  state: {
    hasSomeClass: false,
    get buttonText() {
      // Change the text of the button dynamically depending on the state.
      return state.hasSomeClass ? state.removeClassText : state.addClassText;
    },
  },
  actions: {
    toggleClass() {
      state.hasSomeClass = !state.hasSomeClass;
    },
  },
});

[eirichmond]

Thanks for the clarity, @luisherranz. It's much appreciated and certainly helps my understanding. So when you refer to a (p)react application, the Interactive API is completely independant of react.js then right?

Regarding my question pertaining to AJAX calls or client-to-server interaction, where you would traditionally use wp_ajax_ and wp_ajax_nopriv_ in conjunction with event listeners by localizing jQuery scripts, these can be found across three resources in the Developer Resources related to using JavaScript in plugins:
https://developer.wordpress.org/plugins/javascript/jquery/
https://developer.wordpress.org/plugins/javascript/ajax/
https://developer.wordpress.org/plugins/javascript/enqueuing/

To be more specific, I'd like to know how you would use the Interactive API to send data back to the server and also trigger a function to use that data, in the same way, we would using the resources listed above. For example, localizing a script, using jQuery to send a POST or AJAX request to a specific PHP function to process that data. I hope this makes sense?

[Spekachu]

I'm also interested in a response concerning AJAX calls and client-to-server interaction.

[samueljseay]

@eirichmond @Spekachu I recently wrote an example for a workshop that covers what you're asking for here, so I thought it might be useful to you: https://github.com/samueljseay/iapi-todos-example/

Specifically for performing ajax requests, you'll need to use generators as specified in the docs: https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/#store-client-methods (under 'Async actions'), while you're performing async actions you can update state to represent things like status indicators or errors.

I've tried adding the wp-api dependency to the action hook enqueue_block_editor_assets but this doesn't work, I've also tried using the filter hook register_block_type_args but this also doesn't work, what is the standard practice for setting this up?

@eirichmond right now because interactivity API is loaded as a module (and its one of the only supported modules right now) you can't directly import the other @wordpress packages. I don't know if there is a "standard practice" right now. But I do now they plan to add support for other packages soon. 🎉

As a workaround I enqueue it manually in my block render and then access it via the window. At least that might get you started if you want to play around.

I'm not yet an expert in the interactivity API, so I welcome critique or feedback on my workshop example. 🙇

[eirichmond]

I presume you need to use the rest api and add the wp-api during the build so its added to the index.asset.php file for use in the veiw.js file but I can't currently figure out how to do this?
I've tried adding the wp-api dependency to the action hook enqueue_block_editor_assets but this doesn't work, I've also tried using the filter hook register_block_type_args but this also doesn't work, what is the standard practice for setting this up?