eliot-akira
commented
3 months ago This is turning out to be an interesting feature. I found a library called JSON Logic, a cross-language specification for building complex rules that can be serialized as JSON and evaluated in the browser or server side.
It was the perfect starting point - I rewrote their implementation in TypeScript and PHP to fully customize for our needs. To confirm they're correct and compatible with each other, there's a suite of test cases written in JSON (tests.json).
Logic rules
The main concept is a "logic rule", which is always in this shape.
type Rule = {
[key: Operator]: Value | Value[]
}
type Operator = 'and' | 'or' | 'not' | ...
type Value = Rule | anyIt's a plain object (associative array) with a single key, which is an operator. It has one or more values, which themselves can be a logic rule. Here's the list of supported operators, like and, or, not, == (equal), != (not equal), in.
Example of logic rules
{
'==': [1, 2]
}..is equivalent to the condition, 1 == 2.
{
and: [
{ '>': [1, 2] },
{ '<': [3, 4] }
]
}..is (1 > 2) && (3 < 4).
Logic tag
The new Logic tag is a way to build conditional rules using Rule, And, Or, and Not tags.
<Logic name=example action=hide>
<Rule control=text_1 value="some value" />
</Logic>The above creates an object like:
{
name: 'example',
action: 'hide',
logic: {
and: [
{ rule: { control: 'text_1', value: 'some value' } }
]
}
}Logic tag attributes
name- Name of logic (required)compare- How rules are combined:and,or,not(optional - default:and)- All other attributes are passed as is to the logic object
Example of complex rules
<Logic name=weekend_webinar>
<Rule taxonomy=event_type term=webinar />
<Or>
<Rule field=event_date value=Saturday />
<Rule field=event_date value=Sunday />
</Or>
</Logic>That creates JSON logic like:
{
name: 'weekend_webinar',
logic: {
and: [
{ rule: { taxonomy: 'event_type', term: 'webinar' } },
{
or: [
{ rule: { field: 'event_date', value: 'Saturday' } },
{ rule: { field: 'event_date', value: 'Sunday' } }
]
}
]
}
}Rule tag
The Rule tag is generic. It accepts any attributes, and simply passes them to the rule it creates.
Internally, it uses a special operator rule, which calls a given dynamic rule evaluator. For example, it can be evaluated using If tag on the server side. Or a custom evaluator on the frontend to determine visibility conditions based on block control values.
And, Or, Not tags
These tags combine rules in different ways.
All rules must be true
<And>
<Rule ... />
<Rule ... />
</And>At least one rule must be true
<Or>
<Rule ... />
<Rule ... />
</Or>Rule must be false
<Not>
<Rule ... />
</Not>At least one rule must be false
<Not>
<Rule ... />
<Rule ... />
</Not>All rules must be false
<Not>
<Or>
<Rule ... />
<Rule ... />
</Or>
</Not>Pass logic to other tags
The If and Loop tags now support a logic attribute, which applies the logic defined with that name, using the If tag to dynamically evaluate rules.
<If logic=weekend_webinar>
Weekend seminar: <Field title />
<Else />
Weekday seminar: <Field title />
</If>It's a better version of logic variables. For backward compatibility, the If tag falls back to any logic variable defined with <Set logic>.
Using <Loop logic> will filter items that match the given logic.
<Loop post_type=event logic=weekend_webinar>
Weekend seminar: <Field title />
</Loop>It's a shortcut that's equivalent to:
<Loop post_type=event>
<If logic=weekend_webinar>
Weekend seminar: <Field title />
</If>
</Loop>This is less efficient than using query parameters, but useful for post-processing the query result.
Functions
PHP
Here's where the Logic tag is defined, language/logic/tag.php. It includes utility functions like:
use tangible\template_system;
$logic = template_system\get_logic_by_name( $name );
if ($logic !== false) {
$result = template_system\evaluate_logic( $logic, $evaluator );
}TypeScript
The core logic functions are currently in logic/index.ts.
During development, we can maybe alias @tangible/logic to ./vendor/tangible/template-system/logic. I plan to publish it as an NPM package when its interface is stable.
import { evaluate } from '@tangible/logic'
const result = evaluate( logic, evaluator )The rule evaluator takes a rule and returns boolean (true or false). For example:
const logic = {
rule: { control: 'example', value: '123' }
}
const data = {
example: '456'
}
function ruleEvaluator(rule) {
const { control, value } = rule
return data[ control ] === value
}
const result = evaluate( logic, ruleEvaluator )@nicolas-jaussaud Hopefully that's a good foundation and enough info to get you started on converting the visibility conditions syntax for block controls (TangibleInc/blocks#1).
@BenTangible @juliacanzani It would be lovely if you could kick the tires and take it for a test drive. The above description can probably serve as a rough draft for a documentation page.
nicolas-jaussaud
BenTangible
IfLoopFrom Tangible Blocks: Visibility conditions - Syntax change:
Build logic
Use with
LoopUse with
IfUse with
Control