Visibility conditions - Syntax change

[nicolas-jaussaud]

Hi @BenTangible @eliot-akira @juliacanzani!

I'd like to re-open the discussion from last year regarding the visibility conditions in block controls and validate/discuss a potential syntax change before starting to work on it

The previous discussion took place in the comments of this pull request and it was about the following:

1. We have really similar syntax for 2 different things
2. We need to migrate the old visibility condition system of the blocks plugin to the new one from tangible fields
3. At some point, we want a more broad visibility condition system on the client side (probably unrelated to the one in tangible fields)

1. Similar syntax for 2 different things

Currently we have this syntax, which is a regular L&L condition that can be used inside a template and will be evaluated on the server side:

<If check="{Get control=loop_type}" is_not value="">
   <span>text</span>
</If>

We also have this syntax that can only be used inside the control tab of a block, and that will be evaluated dynamically on the client side:

<If control="text_1" value="text value"> 
   <Control type="text_2" name="text_2" label="Text value"/>
</If>

On the controls tab of a block, regular L&L <If> conditions can be used which can be misleading as you can't mix them with dynamic control conditions

The idea was that we switch to a completely different syntax for the second snippet, to make it clear that it's a different concept

2. Migrate current visibility system to the one from fields

The current visibility system in blocks is a little hacky currently, because it was initially implemented when we used the native controls of each builder (so there is a lot of builder specific logic implemented)

Now that we have our own controls from the fields module, we should probably switch to the visibility condition system we implemented there as it will reduce the amount of builder specific code (it will be more reliable and easier to maintain)

We should probably try to do this migration and the syntax change at the same time

3. General visibility condition system on the client side

We discussed the possibility to implement a more general front-end <If> in the future, but my understanding is that it will be a completely different feature, both in the syntax used an in the implementation (which means I don't really have to take that into account in blocks right now)

Is that the case?

---

If what I said above is OK, a syntax I suggested last year was something like that:

<Control type="text" name="text_3" label="Text 3">
  <Map conditions>
    <Key text_1>value needed in text_1</Key>
    <Key text_2>value needed in text_2</Key>
  </Map> 
</Control>

Ideally I would like to be able to just "translate" the configuration we have in tangible-fields from PHP to L&L:

$fields->render_field('text_3', [
  // ...
  'condition' => [
    'action'    => 'show',
    'condition' => [
      '_and' => [
        ['text_1' => [ '_eq' => 'value needed in text_1']],
        ['text_2' => [ '_eq' => 'value needed in text_2']]
      ]
    ]
  ]
];

But my attempts to do it results in something very wordy and I'm not sure it's usable:

<Control type="text" name="text_3" label="Text 3">
  <Map conditions>
    <Key action>show</Key>
    <Map conditions>
      <List and>
        <Map text_1>
          <Key operator>_eq</Key>
          <Key value>value needed in text_1</Key>
        </Map>
        <Map text_2>
          <Key operator>_eq</Key>
          <Key value>value needed in text_2</Key>
        </Map>
      </Map>
    </Map>
  </Map> 
</Control>

If you guys have some idea of syntax we could use let me know!

[eliot-akira]

We discussed the possibility to implement a more general front-end in the future, but my understanding is that it will be a completely different feature, both in the syntax used an in the implementation (which means I don't really have to take that into account in blocks right now)

Is that the case?

Yes - for the Frontend If feature, I'm leaning toward using special tag attributes, in a similar direction as:

• Alpine.js, which has "directives" called x-if and x-show
• and what WordPress/Gutenberg team is working on, the Interactivity API with HTML directives.

Especially the latter, the use of data-wp attributes makes it clear that it's a browser-side function. It would be interesting to consider how we could make use of these built-in directives.

---

Now that we have our own controls from the fields module, we should switch to the visibility condition system .. We should try to do this migration and the syntax change at the same time.

That makes sense.

By the way, the link goes to fields.localhost which we can't see, hehe. But with WP Playground, I think it will become more common to simply link to a temporary site's admin screen, like this (an L&L demo I just created by hand-writing JSON in the URL, a feature called Blueprints API) . I'm studying how to achieve this with plugin features during development, from a Git commit/branch/pull request, as a live preview.

---

Ideally I would like to be able to just "translate" the configuration we have in tangible-fields from PHP to L&L

The approach sounds good, to let the user build conditional rules as a data structure, more or less directly. But maybe Map, List, and Key are too low-level.

This topic is related to If tag in general, and Loop too. Currently it's difficult to construct complex conditions (and queries) with operators like and, or, equal. For a while I've been thinking of a Query tag that lets users build safe and efficient SQL queries - but translating it to HTML syntax gets verbose quickly. I wonder if there's a solution that can unify and simplify these concerns.

---

It feels like Rule could be a tag, like:

<Condition action=show>
  <And>
    <Rule key=text_1 value="example-1" />
    <Rule key=text_2 value="example-2" compare=not_equal />
  </And>
</Condition>

[BenTangible]

On the controls tab of a block, regular L&L <If> conditions can be used which can be misleading as you can't mix them with dynamic control conditions

Could someone clarify what "dynamic control conditions" means in this context? Are you saying that in the controls tab, the value attribute can only accept text values, not dynamic values? I just want to understand the limitations of the current and proposed approaches.

It certainly would make the language easier to learn if there was a consolidated logic syntax that worked differently behind the scenes, but @eliot-akira has shared the "leaky abstraction" Wikipedia article with me enough times that I understand how this can paint us into a corner. 😄

---

This is pretty neat.

<Condition action=show>
  <And>
    <Rule key=text_1 value="example-1" />

Most graphic logic-builder UIs use nested rule groups with the ability to select whether the group uses and or or logic, so this should be pretty familiar to users. Is there a reason we didn't/can't use that approach in the context of complex conditions (i.e. logic variables)?

[eliot-akira]

I think what @nicolas-jaussaud meant by "dynamic control conditions" are conditions that change in the browser ("frontend If"), in contrast to normal If tag conditions that are decided once on the server side. So this example:

<If control="text_1" value="text value"> 

It only works on the frontend, and reacts (show/hide its content) when the control is changed. It's kind of just pretending to be an If tag. (Yes, leaky abstraction strikes again!)

---

About logic variables, the way it works currently is kind of primitive. When setting a logic variable, it simply renders its content and checks that there is no false inside (for ALL condition), or at least one true (for ANY condition). It probably needs to be re-designed to support combining rules like AND and OR.

---

Speaking of logic-builder UIs, one of the original references for the visibility logic UI was Beaver's.

(From: Beaver Themer: Conditional logic APIs)

What's interesting is that instead of providing operators like AND and OR, they solve it with a fixed structure: each rule group consists of rules that are combined with AND; and rule groups are combined with OR. Roughly, it looks like:

type Condition = {
  action: 'show'          // Maybe other actions in the future
  ruleGroups: RuleGroup[] // Combined with OR
}
type RuleGroup = Rule[]   // Combined with AND
type Rule = {
  fieldType: string
  fieldName: string
  operator: 'equal' | 'not_equal' | ..
  value?: string
}

It's a flat structure with no nested conditions, which makes it easier to evaluate. I wonder though, if there might be certain conditions that this structure is not able to express. But I'm guessing that this provides enough flexibility for most practical purposes.

[nicolas-jaussaud]

Thank you for your answers!

By the way, the link goes to fields.localhost which we can't see, hehe. But with WP Playground, I think it will become more common to simply link to a temporary site's admin screen, like this (an L&L demo I just created by hand-writing JSON in the URL, a feature called Blueprints API) .

Oops, I will edit the link

I meant to use this site (still not as accessible as a WP Playground site as it requires to log in, but at least it can be reached haha)

Could someone clarify what "dynamic control conditions" means in this context?
I think what @nicolas-jaussaud meant by "dynamic control conditions" are conditions that change in the browser

Yes sorry that wasn't clear, by "dynamic" I indeed meant evaluated on the front-end

This is pretty neat.

  <Condition action=show>
   <And>
    <Rule key=text_1 value="example-1" />

I like this syntax too, it seems that we don't lose any features from fields and it's still very readable

Maybe we could use action=show and <And> as default values, so that we can also use a shorter syntax like this one for simpler cases:

<Condition>
  <Rule key=text_1 value="example-1" />
  <Rule key=text_2 value="example-2" compare=not_equal />
</Condition>

Speaking of logic-builder UIs, one of the original references for the visibility logic UI was Beaver's.
What's interesting is that instead of providing operators like AND and OR, they solve it with a fixed structure: each rule group consists of rules that are combined with AND; and rule groups are combined with OR.

We kept the same kind of structure for the conditional logic panel we started in fields too (it's not used in blocks yet but there is an example of it here)

[BenTangible]

"dynamic control conditions" are conditions that change in the browser ("frontend If"), in contrast to normal If tag conditions that are decided once on the server side

Thanks for the clarification. It makes sense that our frontend-If and standard/server If would work differently, have access to different data, and have different syntaxes. But then wouldn't it make sense for control visibility logic and the frontend-If logic to use the same syntax?

---

there might be certain conditions that this structure is not able to express

I've noticed that a lot of logic UIs enforce a hierarchy like that (ands inside ors or vice versa), but that's always seemed unnecessarily limiting to me. Mailchimp, for example, does the opposite of Beaver Builder. Let's say I wanted to display a label on "webinar" events on a weekend. The logic would be (event type = webinar) AND ((date = Saturday) OR (date = Sunday)). Doing that with Beaver's logic structure would involve some repetition.

[eliot-akira]

Mailchimp's logic UI is interesting to compare. The main difference compared to Beaver's is that the user can choose between top-level AND or OR, which determines how rule groups are combined.

Most of their examples have top-level OR, and rules combined with AND. Same as Beaver:

This example has top-level AND, and rules combined with OR.

Otherwise, it looks to be a flat structure with no nested conditions within each rule. The article calls it "nested", but it's only one level deep: rules within rule groups.

It's more flexible than Beaver's, but maybe more confusing to decide when top-level AND is better than top-level OR. And the fact that the rules are implicitly combined with either OR or AND, depending on what the top-level operator is.

---

I like how Nicolas reduced it down to:

<Condition>
  <Rule key=text_1 value="example-1" />
  <Rule key=text_2 value="example-2" compare=not_equal />
</Condition>

I tend to prefer explicitly defining things, like <Condition compare=and>, but I guess it's intuitive enough (?) that all rules are combined with AND by default. According to Beaver and Mailchimp's logic UI structure, that means rule groups are combined with OR by default.

To take it up a notch, I'll try to express Ben's example: (event type = webinar) AND ((date = Saturday) OR (date = Sunday)).

<Logic>
  <Rule key=event_type value=webinar />
  <RuleGroup compare=or>
    <Rule key=date value=Saturday />
    <Rule key=date value=Sunday />
  </RuleGroup>
</Logic>

At first I used And and Or tags, but I replaced with a RuleGroup to make it clear that it only supports a flat structure (only rules within rule groups). Also, top-level Rule is implicitly a group with a single rule.

That seems easy enough to read and write, while being flexible enough to practically express any conditions.

---

..OK, I changed the code example above, from Condition to Logic, since the latter is shorter. I think it makes sense that a Logic tag always returns true or false.

To go further: the Logic tag can have a name, which would assign it to a logic variable. Then it can be passed to an If tag, like:

<Logic name=weekend_webinar>
  ...
</Logic>

<If logic=weekend_webinar>
  ...
</If>

Not sure how exactly that would fit with visibility conditions though. And on second thought, this use of Logic would need to be a lot more flexible, where each Rule is like an If tag (supporting all If conditions).

<Logic name=weekend_webinar>
  <Rule taxonomy=event_type term=webinar />
  <RuleGroup compare=or>
    <Rule field=event_date value=Saturday />
    <Rule field=event_date value=Sunday />
  </RuleGroup>
</Logic>

<Loop post_type=event>
  <If logic=weekend_webinar>
    Weekend seminar: <Field title />
  </If>
</Loop>

..Or better yet, pass the logic to the Loop tag itself.

<Loop post_type=event logic=weekend_webinar>
  Weekend seminar: <Field title />
</Loop>

[eliot-akira]

I'll try to bring the discussion back to the original question. The idea about a Logic tag to build complex rules, it might be useful and relevant - but it's like a fancy version of If tag, which still works on server side only.

OK, to think this through, I'll summarize my understanding so far. What we need is a way to define rules that are evaluated on the frontend, and a syntax to conditionally show/hide controls based on those rules.

The current syntax looks like:

<If control="text_1" value="text value"> 
   <Control type="text_2" name="text_2" label="Text value"/>
</If>

This only works in the Controls tab of the block template edit screen. The way <If control> works is completely different from regular If tag. (It's implemented in includes/block/controls/template.) Based on tag attributes and content, it builds rules to add to visibility conditions. These conditions are passed to each builder integration's "frontend", like in includes/integrations/gutenberg/enqueue.php. There's a JavaScript utility called ControlVisibility (in assets/src/template-controls-visibility) that evaluates the conditions to true or false. Each builder integration uses this to implement build-specific logic to show/hide controls. This is the old way of doing things.

There's a new and better way to do visibility conditions in the Fields module. The heart of it is the JavaScript function evaluateCondition in assets/src/visibility/evaluate.js. It supports operators like _eq (equal), _lte (less than or equal to), etc., similar to MongoDB's query operators. (I personally prefer a more human-readable naming, like equal and less_than_equal, without leading underscore.) I like that this is a general-purpose evaluator, not tied to controls or visibility. This could be useful for the "frontend If" feature in the future.

Ideally, it would be nice if we can use the same data structure for conditional rules on the frontend and server side, with compatible evaluators written in JavaScript and PHP.

So, I'd suggest implementing something like a Logic tag, where users can build rules using RuleGroup and Rule tags. These rules can be passed to the If tag for server-side evaluation; or, they can be passed to the Control tag to define visibility conditions.

Possible syntax to express the same logic as the example above:

<Logic name=example>
  <Rule control=text_1 value="some value" />
</Logic>

<Control type="text_2" name="text_2" label="Text value" logic=example />

This will show the second control if the first control has a specific value. Internally, I suppose it will work similarly as the current syntax, where the rules are added to the visibility conditions passed to the frontend JS, to evaluate and show/hide controls dynamically.

[eliot-akira]

I've started planning for the Logic tag in the Template System.

• Logic tag to build and evaluate conditional rules template-system#115

@nicolas-jaussaud I'll work in the direction we've discussed so far, and when there's some kind of interface prepared, we can "meet in the middle" somehow - where you can import some functions to use in Tangible Blocks and/or Fields, to replace the current syntax for visibility conditions. Maybe I'll prepare the basics first, and we can work together to develop it further based on what's needed.

[eliot-akira]

OK, just to make a note of this, the foundation of the Logic module is prepared.

• Logic tag to build and evaluate conditional rules template-system#115

And now we can work on integrating it with the Fields module and the Blocks plugin.

• Block control visibility conditions: Integrate with Logic module #2