Reference notation syntax

[luisherranz]

Right now, we are using the dot notation (.) to reference specific properties of the store in the directive values:

<div data-wp-bind--hidden="state.isHidden"></div>

We also support a negation prefix (!) because that's very easy to implement and very convenient at the same time:

<div data-wp-bind--hidden="!state.isVisible"></div>

But when a developer sees !state.isVisible, it's impossible to infer that this is not JavaScript.

Thanks to the new store() API, we will deviate a little bit from JavaScript syntax, but only when using non-default namespaces:

<!-- Accessing the default namespace -->
<div data-wp-bind--hidden="!state.isVisible"></div>

<!-- Accessing another namespace -->
<div data-wp-bind--hidden="anotherStore::!state.isVisible"></div>

It helps, but referencing non-default namespaces will be rare.

There's also the question of whether we want to add more logic apart from ! or not, like ==:

<div data-wp-class--is-selected="state.selected == context.id"></div>

I'm not in favor of doing that, but I wanted to mention it anyway. I think it will lead to more confusion (because we will never be able to match people's expectations), and it will increase the size of the runtime.

In the past, we briefly discussed replacing the . notation with something else, for example slashes (/):

<div data-wp-bind--hidden="state/isHidden"></div>

It feels a bit weird to me at this moment, but it's true that all changes feel like that until you get used to them (it happened with the data- and the --) 😄🤷‍♂️

It's also weird when you mix it with the negation ! operator:

<div data-wp-bind--hidden="!state/isVisible"></div>

Although when mixed with the non-default namespace doesn't look that bad to me:

<div data-wp-bind--hidden="anotherStore::state/isHidden"></div>

So what are your thoughts:

• Should we keep the dot . notation because it's nice and focus our efforts on making it very clear that it's not JavaScript in the documentation?
• Or should we replace it with something else? If so, what?

---

cc: @juanmaguitar, @ryanwelcher, @DAreRodz, @SantosGuillamot, @sunyatasattva

[juanmaguitar]

I think a property like data-wp-bind--hidden should accept any form of Javascript expression that returns a boolean value:

• A logical operation: !, && o ||
• A comparison such as ===, !=, >
• Any value or variable that can be converted into a Boolean
• A combination of any of these

And then clarify in the docs, any limitations for values accepted

[luisherranz]

The problem is that we can't run JavaScript on the server, so we would need to create a PHP parser that understands those tokens. Also, we would need to build a similar parser in the frontend, because we shouldn't use eval to avoid security problems and comply with strict content security policies.

Building a JS parser, even a simple one, is a complex task. And it's also confusing because it's not real JS, but it looks like real JS, so it will likely break a lot when people use it for things that are not supported and they will think that it's broken. It may also increase the runtime size significantly.

I know that some projects have done similar things in the past, but my opinion is not to open that box of worms. And in our experimentation, we've seen that, apart from the negation operator (!), it's not that helpful anyway.

Finally, we have to be very mindful of our limited resources and something like that could take some time away from more important things.

So, I strongly disagree 😄

[juanmaguitar]

Thanks for the clarification, Luis. I understand better the context for this now 🙂
In that case, I would stick it to values such as state.isVisible or !state.isVisible and explain in the docs the limitations for these values and the reasons for that

I disagree with the use of non-JS intuitive forms such as state/isHidden
For namespaces, maybe a syntax such as [anotherStore]!state.isVisible could be a nicer alternative.

[luisherranz]

Perfect. Thank you for your feedback, Juanma!

[SantosGuillamot]

At this moment, I would stick with the dot . notation and explain it properly in the documentation. Although maybe it is because I am not used to the other syntax as you say (state/isHidden for example).

With state.isVisible, we are referencing an object that is (mostly) defined in JS. It seems easier to me to relate it to the store. If we keep the dot notation, we use the same syntax in the directives and in the store. Inside an action or in derived state for example we would also use state.isVisible.

I am unfamiliar with PHP/WordPress errors but, could we throw a descriptive error explaining that it is not JS when users include not supported syntax inside a directive?

[luisherranz]

Yes, good point on improving our errors 🙂

[sunyatasattva]

Thank you @luisherranz for opening this discussion. For me, the dot notation definitely caused some confusion while reading the docs and your mention of the “path-notation” felt like it much more clearly communicated the intention of the API.

However, after giving it some thoughts, I personally think it's perhaps for the best to keep the dot notation. You mention that you don't plan to ship any other features besides the negation ! in the parser, in order not to get into scope creep, battling with people's ever-expanding expectations and runtime/performance considerations.

These are all excellent considerations, however, I now feel that perhaps keeping the dot notation keeps these things a bit more open for posterity. These are early days of the Interactivity API and, though you certainly have much more context and insight than I do, I think it'd be really hard to predict where it would go from here on out into the years. Keeping the dot notation, we make it much easier for our children and grandchildren (🤭) to expand its capabilities into parsing more expressions as requested by some of the commenters and should the need arise, without breaking backwards compatibility, or making the parser too complex.

This might never happen, but given our commitment to backwards compatibility, I think it'd be quite forward thinking to design something that's more open to the unknowns of the future, the decisions of the community and also possible leaps and improvements of the web platform itself.

Given this, I think focusing on being clear in the docs should solve the problem I had, and perhaps trying to catch those errors like it was mentioned above, would make sure that people who only skimmed the docs or worked on hacking away something by example will get guidance and the least frustration possible.

[luisherranz]

Makes sense 🙂

[luisherranz]

I'm going to close this as resolved because there seems to be a general consensus on keeping the dot notation, but feel free to reopen it if you feel like this should be discussed further.