Actions

Introduction to Actions

Actions in the Vyuh framework provide a powerful way to add interactivity to your application. They define what happens when users interact with content blocks, such as clicking a button, submitting a form, or navigating between screens.

Actions are designed with a composable architecture that allows for multiple operations to be executed in sequence from a single user interaction.

Action Object Structure

An action object consists of:

1. Title - An optional descriptive name for the action
2. Configurations - A list of action configurations that define what happens when the action is triggered

const action = {
  _type: 'vyuh.action',
  title: 'Submit Form',
  configurations: [
    // List of action configurations to execute
    { _type: 'vyuh.action.navigate', url: '/success', isAwaited: false },
    {
      _type: 'vyuh.action.openUrl',
      url: 'https://example.com',
      isAwaited: true,
    },
  ],
}

This structure allows you to create complex workflows by chaining multiple operations together in a single action.

Action Configurations

Each action configuration represents a specific operation that can be performed. The configuration includes:

• _type - Identifies the type of operation (e.g., navigation, opening URLs)
• isAwaited - Determines whether to wait for this operation to complete before proceeding
• Additional properties - Specific to each operation type

The Vyuh framework includes several built-in action configurations. Here are the most commonly used ones:

// Navigation action
const navigateAction = {
  _type: 'vyuh.action.navigation',
  title: 'Go to Details',
  url: '/details',
  navigationType: 'push',
  isAwaited: false,
}

// Open URL action
const openUrlAction = {
  _type: 'vyuh.action.openUrl',
  title: 'Visit Website',
  url: 'https://example.com',
  mode: 'platformDefault',
  isAwaited: true,
}

Multiple Operations in a Single Action

One of the most powerful features of Vyuh actions is the ability to execute multiple operations in sequence. This allows you to create complex workflows from a single user interaction.

const submitFormAction = {
  _type: 'vyuh.action',
  title: 'Submit Form',
  configurations: [
    // 1. Navigate to success page
    {
      _type: 'vyuh.action.navigation',
      url: '/success',
      navigationType: 'push',
      isAwaited: false,
    },
    // 2. Open documentation in browser
    {
      _type: 'vyuh.action.openUrl',
      url: 'https://docs.example.com/success',
      mode: 'platformDefault',
      isAwaited: true, // Wait for browser to open
    },
  ],
}

In this example, a single “Submit Form” action performs two operations in sequence:

1. Navigates to a success page
2. Opens documentation in the browser (and waits for completion)

Awaited vs Non-Awaited Execution

Each action configuration can specify whether it should be awaited before proceeding to the next configuration:

{
  _type: "vyuh.action.saveData",
  isAwaited: true, // Wait for this to complete before continuing
  // other properties
}

When an action is executed:

1. The system iterates through each configuration in the configurations array
2. For each configuration:
   • If isAwaited is true, it waits for that configuration to complete before moving to the next one
   • If isAwaited is false, it executes the configuration and immediately proceeds to the next one

This allows you to control the flow of operations, ensuring that dependent operations only execute after their prerequisites have completed.

Tip

Use isAwaited: true for operations that must complete before subsequent operations can proceed, such as data validation or saving. Use isAwaited: false for operations that can run independently, such as analytics tracking or UI updates.

Conditional Actions

The Vyuh framework also supports conditional actions, which allow you to dynamically choose which action to execute based on a condition:

{
  _type: "vyuh.action.conditional",
  condition: {
    configuration: {
      _type: "vyuh.condition.boolean",
      value: true
    }
  },
  cases: [
    {
      value: "true",
      action: {
        // Action for true condition
        _type: "vyuh.action",
        configurations: [
          { _type: "vyuh.action.navigation", url: "/dashboard" }
        ]
      }
    },
    {
      value: "false",
      action: {
        // Action for false condition
        _type: "vyuh.action",
        configurations: [
          { _type: "vyuh.action.navigation", url: "/login" }
        ]
      }
    }
  ],
  defaultCase: "false"
}

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 Action Types

The Vyuh framework includes several common action types. Here are the two most frequently used:

Navigation Actions

// Push a new route
{
  _type: "vyuh.action.navigation",
  navigationType: "push",
  url: "/products/123"
}

// Replace the current route
{
  _type: "vyuh.action.navigation",
  navigationType: "replace",
  url: "/products/123"
}

External URL Actions

// Open URL in default browser
{
  _type: "vyuh.action.openUrl",
  url: "https://example.com",
  mode: "platformDefault"
}

Using Actions with Content Blocks

Actions can be attached to content blocks to make them interactive:

// Card with a navigation action
const cardWithAction = {
  _type: 'vyuh.card',
  title: 'My Card',
  description: 'Click to view details',
  action: {
    _type: 'vyuh.action',
    title: 'View Details',
    configurations: [
      {
        _type: 'vyuh.action.navigation',
        url: '/details/123',
        navigationType: 'push',
      },
    ],
  },
}

Best Practices

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

1. Use descriptive titles - Give your actions meaningful names that describe their purpose
2. Chain related operations - Group related operations in a single action for better organization
3. Be mindful of awaited operations - Only use isAwaited: true when necessary to avoid blocking the UI
4. Handle errors - Include error handling in your action chains
5. Use conditional actions - Leverage conditional actions to create dynamic user experiences
6. Keep actions focused - Each action should have a clear, specific purpose