Helper function for adding data-wp-context in PHP

[luisherranz]

We were thinking about adding a function helper for data-wp-context in PHP.

Something like this:

<?php
$context = array(
  'videoId' => $trailer_id
);
?>

<div
  <?php echo $wrapper_attributes; ?>
  data-wp-context=<?php echo wp_context( $context ); ?>
>
   ...
</div>

Internally, it should process the array with things like esc_attr or wp_json_encode. It could potentially take care of security.

Let's discuss:

• What should it be called?
• What processing should it do by default?
• What extra options would it need?

---

Related PR: WordPress/wp-movies-demo#41

[westonruter]

I'm not familiar with there being any WordPress "template tag" that outputs the quoted value of an HTML attribute. Rather, they output either the value of the attribute (the_title_attribute()) or the key/value pair (get_block_wrapper_attributes()). To avoid having to output the name of the data attribute, which I believe would always be the same (and to facilitate possible future changing), I suggest it be output by the template tag as well. So something like:

<?php
$context = array(
  'videoId' => $trailer_id
);
?>

<div
  <?php echo get_block_wrapper_attributes(); ?>
  <?php echo wp_context( $context ); ?>
>
   ...
</div>

Seeing this, another possibility is the context could be passed to get_block_wrapper_attributes() since it already accepts extra attributes. But since the context could be added to arbitrary tags and not just wrappers, then probably not.

As for naming, maybe wp_get_context_attribute()?

[luisherranz]

I suggest it be output by the template tag as well

I kind of like the explicitness of leaving data-wp-context in the markup, but that could also work. We can try to see how it feels.

As for naming, maybe wp_get_context_attribute()?

Whatever we choose, it'd also be great to think of a possible JavaScript counterpart that uses the same name, so people don't need to remember both.

import { getContextAttribute } from "@wordpress/interactivity";

const Save = ({ attributes }) => {
  const context = {
    videoId: attributes.trailerId,
  };

  return (
    <div data-wp-context={getContextAttribute(context)}>
      ...
    </div>
  );
};

Or this if it includes the attribute name:

<div {...getContextAttribute(context)}>

[yscik]

Could there be an even more generic helper function, sort of a React.createElement equivalent, that is directive-aware?

echo wp_element( 'div', 
	[  
		// Attributes & directives
		'context' => [ 'videoId' => $trailer_id ], 
		'on.click' => 'play',
		'style' => [ '--img-url' => $img_url ],
	], 
	[
		// Children
		 __('Play') 
	] );

I know it's not exactly the main scope, but it can introduce the feature with a nicer DX, and reduce the need to switch between HTML/PHP/JS contexts and syntax that much. (At the cost of being less explicit and HTML-like.)

Maybe this makes more sense as a part of the HTML tag processor?

Either way, the current way of building HTML with string concatenation or PHP tags thrown in is not exactly a comfortable experience, not to mention error-prone. With the Interactivity API it would be an even more frequent thing developers do, so it could be worth pushing for an improved solution now.

[luisherranz]

the current way of building HTML with string concatenation or PHP tags thrown in is not exactly a comfortable experience

Along with the Interactivity API, we are promoting the adoption of the render.php file instead of the render_callback function. Is there any reason why you see the need to continue using a render_callback?

Example of the render.php file

Could there be an even more generic helper function, sort of a React.createElement equivalent, that is directive-aware?

For reference, @dmsnell started exploring something similar to what you propose here: WordPress/wordpress-develop#4065

[dmsnell]

I noted in WordPress/wordpress-develop#4065 that I no longer like that solution and have proposed an alternative, something that would look more like this and in a sense feels a bit magical in how it is able to perform validation and attribute-level semantics on the data, avoiding the need for all escaping and sanitization I believe (from the calling code)

echo WP_HTML::template(
	'<div data-wp-context.videoId="</%id>" data-wp-on.click="play" style="--img-url: </%url>"></%label></div>',
	array(
		'id'    => $trailer_id,
		'url'   => $img_url,
		'label' => __( 'Play' )
	)
);

[gziolo]

A related issue was opened by @ryanwelcher, discussing helper functions that could write the syntax for actions and selectors.

---

Regarding the context, what is currently supported? Is it possible to write:

<div data-wp-context.videoId="123">
    ...
<div>

---

Seeing this, another possibility is the context could be passed to get_block_wrapper_attributes() since it already accepts extra attributes. But since the context could be added to arbitrary tags and not just wrappers, then probably not.

I wanted to emphasize that get_block_wrapper_attributes() is used only with the outer HTML element, and it's already difficult to use because you need to remember to pass class and style attributes to it.

---

We could also try to handle everything behind the scenes in the following way:

<?php
wp_context( array(
  'videoId' => $trailer_id
) );
?>

<div data-wp-block-wrapper data-wp-context>
   ...
</div

If we need more than one place to use the context:

<?php
wp_context( array(
  'videoId' => $trailer_id
) ); // The context name as 2nd param could default to 'default'
wp_context( array(
  'videoId' => $trailer_id
), 'another-context' ); // The custom name for the context.
?>

<div data-wp-block-wrapper data-wp-context>
    ...
    <div data-wp-context="another-context">
        ...
    </div>
</div

Behind the scenes, we could generate unique ids for every block instance that uses the context:

global $block_directives_context;

$block_directives_context = array(
    'block-abcd-default' => array(
        'videoId' => 123,
    ),
    'block-efgh-default' => array(
        'videoId' => 456,
    ),
    'block-efgh-another-context' => array(
        'videoId' => 789
    ),
);

We would have to expose that also to Javascript and rewrite the HTML to connect it on the client, example for both snippets:

<div data-wp-block-wrapper data-wp-context="block-abcd-default">
   ...
</div

<div data-wp-block-wrapper data-wp-context="block-efgh-default">
    ...
    <div data-wp-context="block-efgh-another-context">
        ...
    </div>
</div

[luisherranz]

Regarding the context, what is currently supported? Is it possible to write: <div data-wp-context.videoId="123">

No, but it won't be hard to implement, even with namespaces: <div data-wp-context.myPlugin.videoId="123">

We would have to expose that also to Javascript and rewrite the HTML to connect it on the client, example for both snippets: <div data-wp-block-wrapper data-wp-context="block-abcd-default">

Also possible and not difficult to implement. We only need to serialize them:

<script type="application/json" id="wp-interactivity-contexts">
  {
    "block-abcd-default": { ... },
    "block-efgh-default": { ... }
  }
</script>

I like both ideas 🙂

[felixarntz]

Alternative to something like wp_context() which is tied to one directive, we could also consider something like WordPress/block-interactivity-experiments#132 (comment) (based on the equivalent JSX suggestion from WordPress/block-interactivity-experiments#132 (comment)).

Regardless of which option we choose, it would be great to align the approaches between JSX and PHP to be of similar nature.

[luisherranz]

it won't be hard to implement, even with namespaces: <div data-wp-context.myPlugin.videoId="123">

Ohhh, I just realized that there's a problem with this syntax because uppercase is sadly not preserved by the DOM parser 🙁

[dmsnell]

@luisherranz attribute and tag names are case-insensitive. CSS class names are maybe the only thing with case sensitivity.

[luisherranz]

There's always the possibility of writing each part in kebab-case.

• Instead of: data-wp-context='{ "myPlugin": { "someBlock": { "isOpen": true } } }
• You could do: data-wp-context.my-plugin.some-block.is-open="true"

Then, inside the context directive, just do context.split(".").map(x => x.replace(/-./g, s => s[1].toUpperCase())).

[luisherranz]

If we finally go with -- in here:

• Instead of: data-wp-context='{ "myPlugin": { "someBlock": { "isOpen": true } } }
• You could do: data-wp-context--my-plugin--some-block--is-open="true"

I guess it's fine 🤷‍♂️😄

[luisherranz]

This is much better with the new store() API, where the namespaces are absorbed:

• New Interactivity `store()` API proposal #53586

You can simply do:

data-wp-context--is-open="true"

and then use it in your store:

store("myPlugin", {
  actions: {
    someAction: () => {
      const { context } = getElement();
      context.isOpen; // true
    },
  },
});

[luisherranz]

It turns out it's not that easy to escape a JSON and place it in an attibute, so we should keep looking into this.

A new idea could be to use a wp_directive() function that inspects what you pass, and if it's an array, it does the necessary escaping. The Tag Processor could have a similar set_directive API.

It would be something like this for render callbacks:

function render() {
  $context = array(
    'someValue' => 'some value',
  );

  return sprintf('
      <div
        %1$s
        %2$s
      >
        ...
      </div>
    ',
    get_block_wrapper_attributes(),
    wp_directive( 'context', $context ),
  );
}

Something like this for render.php files:

<?php
$context = array(
  'someValue' => 'some value',
);
?>

<div
  <?php echo get_block_wrapper_attributes(); ?> 
  <?php echo wp_directive( 'context', $context ); ?> 
>
  ...
</div>

And something like this for the HTML Tag Processor:

function( $block_content ) {
  $p = new WP_HTML_Tag_Processor( $block_content );
  $p->next_tag( 'DIV' );
  $p->set_directive( 'context', $context );
  return $p->get_updated_html();
}

Namespaces are now optional, so they could be included as an option:

wp_directive( 'context', $context, array(
  'namespace' => 'another-namespace',
) );

[luisherranz]

Another idea could be to expose the full data-wp-context name as a function. It's a bit nicer in terms of DX, but it requires one function/method per directive.

<?php
$context = array(
  'someValue' => 'some value',
);
?>

<div
  <?php echo get_block_wrapper_attributes(); ?> 
  <?php echo data_wp_context( $context ); ?> 
>
  ...
</div>

function( $block_content ) {
  $p = new WP_HTML_Tag_Processor( $block_content );
  $p->next_tag( 'DIV' );
  $p->data_wp_context( $context );
  return $p->get_updated_html();
}

Of course, this could be built on top of wp_directive:

function data_wp_context( $context ) {
  return wp_directive( 'context', $context );
}

[dmsnell]

it's trivial to write a helper function to translate between application-level logic and HTML-specific logic. I think that would be a stronger candidate for the long-term health of maintainability inside the HTML API. in other words, I think it will be easier for everyone if we leave the HTML API focused on HTML itself and build adapters to go from our application domains into that.

even here, I'm nervous about recommending a function that takes a Tag Processor as input, because I don't like this pattern since it can lead to hidden logic and surprise mutation. but…

function data_wp_context( $processor, $context ) { … }

that's mostly the same from the programmer's standpoint. further still is one tiny change that gets back to the original proposed design, but adds a name.

list( $context_attribute, $context_value ) = data_wp_context( $context );
$processor->set_attribute( $context_attribute, $context_value );

or the time-honed PHP way

call_user_func_array( $processor->set_attribute, data_wp_context( $context ) );

there's probably a good thing in here that you raise though about an isomorphic PHP/JS JSON-able data translation. the obvious end to the security issues is simply base64-encoding and -decoding them. I think though that all the concerns are actually well-understood and a basic function could safely escape the JSON payload, including any \u0065-style Unicode escapes.

[luisherranz]

This was finally added in WP 6.5: wp_interactivity_data_wp_context

https://developer.wordpress.org/reference/functions/wp_interactivity_data_wp_context/

Closing this as completed 🙂