Conditions

Introduction to Conditions

Conditions in the Vyuh framework provide a powerful way to create dynamic, context-aware content and interactions. They allow your application to make decisions based on various factors such as user state, device characteristics, time, or any custom logic you define.

Conditions are used to:

• Show or hide content based on user authentication
• Display different layouts based on screen size
• Enable or disable features based on feature flags
• Customize user experiences based on user preferences
• Implement A/B testing scenarios

Condition Object Structure

A condition object in Vyuh has a simple structure focused on a single configuration:

const condition = {
  _type: 'vyuh.condition',
  configuration: {
    _type: 'vyuh.condition.boolean',
    value: true,
    // Additional properties specific to the condition type
  },
}

Unlike actions which can have multiple configurations, a condition has a single configuration that defines its evaluation logic. This design ensures that conditions have clear, predictable outcomes.

Condition Configurations

Each condition configuration represents a specific evaluation logic. The configuration includes:

• _type - Identifies the type of condition
• Additional properties - Specific to each condition type

The Vyuh framework includes several built-in condition configurations. Here’s the most basic one:

// Boolean condition
const booleanCondition = {
  _type: 'vyuh.condition',
  configuration: {
    _type: 'vyuh.condition.boolean',
    value: true,
  },
}

Condition Evaluation Process

When a condition is evaluated, it returns a string value that represents the outcome. This string value is then used to select the appropriate content or action.

For example, a boolean condition returns either “true” or “false” as a string:

// Boolean condition evaluation
const booleanCondition = {
  _type: 'vyuh.condition',
  configuration: {
    _type: 'vyuh.condition.boolean',
    value: true,
  },
}

// Evaluates to "true" (as a string)
const result = await executeCondition(booleanCondition)

Using Conditions with Content

Conditions are most commonly used with conditional content blocks to dynamically select which content to display:

const conditionalContent = {
  _type: 'vyuh.conditional',
  condition: {
    _type: 'vyuh.condition',
    configuration: {
      _type: 'vyuh.condition.boolean',
      value: true,
    },
  },
  cases: [
    {
      value: 'true',
      item: {
        // Content to show when condition is true
        _type: 'vyuh.card',
        title: 'Condition is true',
      },
    },
    {
      value: 'false',
      item: {
        // Content to show when condition is false
        _type: 'vyuh.card',
        title: 'Condition is false',
      },
    },
  ],
  defaultCase: 'false', // Fallback if condition evaluation fails
}

In this example:

1. The condition is a simple boolean condition set to true
2. If the condition evaluates to “true”, it displays the first case content
3. If the condition evaluates to “false”, it displays the second case content
4. If the condition evaluation fails, the defaultCase content is displayed

Using Conditions with Actions

Conditions can also be used with conditional actions to dynamically select which action to execute:

const conditionalAction = {
  _type: 'vyuh.action.conditional',
  condition: {
    _type: 'vyuh.condition',
    configuration: {
      _type: 'vyuh.condition.boolean',
      value: true,
    },
  },
  cases: [
    {
      value: 'true',
      action: {
        // Action for true condition
        _type: 'vyuh.action',
        configurations: [
          {
            _type: 'vyuh.action.navigate',
            url: '/dashboard',
          },
        ],
      },
    },
    {
      value: 'false',
      action: {
        // Action for false condition
        _type: 'vyuh.action',
        configurations: [
          {
            _type: 'vyuh.action.navigate',
            url: '/login',
          },
        ],
      },
    },
  ],
  defaultCase: 'false', // Fallback if condition evaluation fails
}

In this example:

1. The condition is a simple boolean condition set to true
2. If the condition evaluates to “true”, it navigates to the dashboard
3. If the condition evaluates to “false”, it navigates to the login page
4. If the condition evaluation fails, it uses the defaultCase

Common Condition Types

The Vyuh framework includes several condition types. Here’s the most basic one:

Boolean Condition

A simple condition that returns a fixed boolean value:

{
  _type: "vyuh.condition",
  configuration: {
    _type: "vyuh.condition.boolean",
    value: true,
    // Optional delay for testing loading states
    evaluationDelayInSeconds: 1
  }
}

Condition Selection Pattern

When a condition is defined in the CMS, it appears as an array with a maximum of one item. The system selects the first (and only) configuration in this array:

// In the React implementation
const config = Array.isArray(data?.configuration)
  ? data?.configuration[0]
  : data?.configuration

This approach allows for a consistent schema structure while enforcing the single-configuration rule for conditions.

Caution

Unlike actions which can have multiple configurations, a condition must have exactly one configuration. This is enforced in the schema with a validation rule: Rule.max(1).

Creating Custom Conditions

You can extend the Vyuh framework with your own custom conditions by creating a new condition configuration class:

// Custom condition for checking user preferences
export class UserPreferenceCondition extends ConditionConfiguration {
  static readonly schemaType = 'app.condition.userPreference'

  readonly preferenceName: string
  readonly preferenceValue: string

  constructor(data: { preferenceName: string; preferenceValue: string }) {
    super(UserPreferenceCondition.schemaType)
    this.preferenceName = data.preferenceName
    this.preferenceValue = data.preferenceValue
  }

  async execute(context: any): Promise<string> {
    // Get user preferences from your app's state
    const userPreferences = getUserPreferences()

    // Check if the preference matches
    const actualValue = userPreferences[this.preferenceName]
    return (actualValue === this.preferenceValue).toString()
  }
}

Then register your custom condition with the Vyuh content system:

import { registerCondition } from '@vyuh/react-feature-system'
import { UserPreferenceCondition } from './conditions/user-preference'

// Register your custom condition
registerCondition(UserPreferenceCondition)

Best Practices

When working with conditions in Vyuh, consider these best practices:

1. Keep conditions focused - Each condition should evaluate a single aspect of the application state
2. Use meaningful condition names - Choose descriptive names for your custom conditions
3. Handle default cases - Always provide a defaultCase for conditional content and actions
4. Consider performance - Avoid expensive operations in condition evaluation
5. Test all branches - Ensure all possible condition outcomes are tested
6. Use composition - Combine conditions with conditional content and actions for dynamic experiences