Conditional Visibility - Visibility Rulesets
Rendering persistent dynamic changes to TryNow components
Background: What are Visibility Rules?
Sometimes it may be necessary to customize components dynamically, not just stylistically. Changes such as customizations for individual states or other experiences require persistent alterations to the logic TryNow components use to render.
To support such use cases, an API is exposed on each TryNow web component allowing for new rules to be added to a components rendering process. These rules are organized into ranked rulesets, which allow for a simple evaluation structure. TryNow calls these "Visibility Rules" and "Visibility Rulesets". All TryNow components have Visibility Rulesets, even if they are empty/static. By modifying a components rules, dynamic changes to TryNow components can be made and persisted through snippets of code in the theme.
How Visibility Rulesets and Rules Work
Components can have 0 or more rulesets, and each ruleset can have 0 or more rules. Rules consist of a 'test' and 'outcome' callback, the latter of which is ran if the former evaluates to true
. A ruleset can only have 1 matching rule — i.e. it breaks evaluation on the first match. However multiple rules can be ran by using multiple rulesets. There is a limit of 10 rulesets per component.
When rules are evaluated at different points during the component's lifecycle, they are sorted by ascending rank.
Heads up!
Currently, Conditional Visibility Rulesets are not supported for Custom Button Implementations.
API Methods
Rules and Rulesets adhere to the structure below:
type VisibilityRule = {
name?: string
rank: number
ruleTest: (() => boolean) | (() => Promise<boolean>)
ruleOutcome: () => void
}
type VisibilityRuleset = {
name?: string
rank: number
rules: VisibilityRule[]
getRule: (rank: number) => VisibilityRule | undefined
addRule: (rule: VisibilityRule) => void
deleteRule: (rank: number) => void
modifyRule: (rank: number, ruleComponents: Partial<VisibilityRule>) => void
}
export type VisibilityRulesets = VisibilityRuleset[]
VisibilityRuleset
Methods
VisibilityRuleset
MethodsaddRule(rule: VisibilityRule)
: Adds a new rule to the ruleset.getRule(rank: number)
: Retrieves a rule by its rank.deleteRule(rank: number)
: Deletes a rule by its rank.modifyRule(rank: number, modifications: Partial<VisibilityRule>)
: Modifies an existing rule.
Example
In the example below, a simple A/B test is represented by window.abTest
. When the variable is set to 'b'
, the rule outcomes will be ran on the page.
// Define the visibility rulesets
const ctaButtonRuleset = window.trynow.createVisibilityRuleset({
rank: 10,
rules: [
{
rank: 0,
ruleTest: () => window.abTest === 'b',
ruleOutcome: () => {
const ctaButton = document.querySelector('#ctaButton');
if (ctaButton) {
ctaButton.style.display = 'block';
}
},
},
],
});
// Apply the rulesets to the components
window.trynow.getComponent('ctaButton', true).then(ctaButton => {
ctaButton.addRuleset(ctaButtonRuleset);
});
Updated 2 months ago