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

• addRule(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);
});