Actions Overview

Actions define what happens in response to events. They are the building blocks of interactivity in Orbis plugins.

Action Structure

Every action has a type and type-specific properties:

json

{
  "type": "update_state",
  "path": "count",
  "value": "{{state.count}} + 1"
}

Action Types

Type	Purpose
`update_state`	Modify page state
`call_api`	Make API requests
`navigate`	Change routes
`show_toast`	Display notifications
`show_dialog`	Show confirmation dialogs
`close_dialog`	Close dialogs
`debounced_action`	Debounce actions
`validate_form`	Validate forms
`reset_form`	Reset form values
`set_loading`	Set loading state
`download`	Download files
`copy`	Copy to clipboard
`open_url`	Open external URLs
`emit`	Emit custom events
`conditional`	Conditional execution
`sequence`	Sequential execution

Using Actions

In Event Handlers

json

{
  "type": "Button",
  "label": "Click Me",
  "events": {
    "on_click": [
      { "type": "update_state", "path": "clicked", "value": true },
      { "type": "show_toast", "message": "Button clicked!" }
    ]
  }
}

In Lifecycle Hooks

json

{
  "on_mount": [
    { "type": "call_api", "api": "getData" }
  ],
  "on_unmount": [
    { "type": "update_state", "path": "selectedItem", "value": null }
  ]
}

Chaining Actions

Actions execute in sequence:

json

{
  "events": {
    "on_click": [
      { "type": "set_loading", "loading": true },
      { "type": "call_api", "api": "save" },
      { "type": "show_toast", "message": "Saved!" },
      { "type": "set_loading", "loading": false }
    ]
  }
}

Event Context

Actions have access to event context via special variables:

Variable	Context	Description
`$event`	All events	Raw event object
`$value`	on_change	New field value
`$row`	Table on_row_click	Row data
`$index`	List item events	Item index
`$item`	List item events	Item data
`$response`	call_api on_success	API response
`$error`	call_api on_error	Error object
`$page`	on_page_change	Page number

Example

json

{
  "type": "Table",
  "dataSource": "state:items",
  "events": {
    "on_row_click": [
      { "type": "update_state", "path": "selectedId", "value": "{{$row.id}}" },
      { "type": "navigate", "to": "/items/{{$row.id}}" }
    ]
  }
}

Error Handling

With call_api

json

{
  "type": "call_api",
  "api": "saveData",
  "on_success": [
    { "type": "show_toast", "message": "Saved!", "level": "success" }
  ],
  "on_error": [
    { "type": "show_toast", "message": "Error: {{$error.message}}", "level": "error" }
  ]
}

Fallback Pattern

json

{
  "type": "call_api",
  "api": "primaryApi",
  "on_error": [
    {
      "type": "call_api",
      "api": "fallbackApi",
      "on_error": [
        { "type": "show_toast", "message": "All APIs failed", "level": "error" }
      ]
    }
  ]
}

Conditional Actions

Execute actions based on conditions:

json

{
  "type": "conditional",
  "condition": "{{state.isValid}}",
  "then": [
    { "type": "call_api", "api": "submit" }
  ],
  "else": [
    { "type": "show_toast", "message": "Please fix errors", "level": "warning" }
  ]
}

Common Patterns

Loading State

json

[
  { "type": "set_loading", "loading": true },
  {
    "type": "call_api",
    "api": "fetchData",
    "on_success": [
      { "type": "update_state", "path": "data", "value": "$response.data" }
    ],
    "finally": [
      { "type": "set_loading", "loading": false }
    ]
  }
]

Optimistic Update

json

[
  { "type": "update_state", "path": "items", "value": "{{state.items.filter(i => i.id !== $itemId)}}" },
  {
    "type": "call_api",
    "api": "deleteItem",
    "on_error": [
      { "type": "call_api", "api": "getItems" },
      { "type": "show_toast", "message": "Failed to delete", "level": "error" }
    ]
  }
]

Form Submission

json

[
  { "type": "validate_form", "form": "myForm" },
  {
    "type": "conditional",
    "condition": "{{state.$formValid}}",
    "then": [
      { "type": "set_loading", "loading": true },
      {
        "type": "call_api",
        "api": "submitForm",
        "args": "{{state.formData}}",
        "on_success": [
          { "type": "show_toast", "message": "Submitted!", "level": "success" },
          { "type": "reset_form", "form": "myForm" },
          { "type": "navigate", "to": "/success" }
        ]
      },
      { "type": "set_loading", "loading": false }
    ]
  }
]

Next Steps

Explore each action type in detail: