@ea-lab/reactive-json-docs/public/rjbuild/docs/getting-started/actions.yaml

Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides

renderView:
  - type: Markdown
    content: |
      # Actions System

      The Reactive-JSON actions system allows you to modify element behavior and appearance based on dynamic conditions. Actions are applied to individual elements and can control visibility, display tooltips, redirect users, or trigger other behaviors based on the current data state.

      Actions enable the UI to adapt automatically based on the application's state. They differ from [reactions](./reactions), which execute in response to user events; actions are evaluated continuously based on data conditions.

  - type: Markdown
    content: |
      ## Basic Syntax

      Actions are defined as part of the `actions` array on any element. Each action has the following structure:

  - type: DefinitionList
    content:
      - term:
          code: what
        details: "The type of action to execute."
      - term:
          code: when
          after: " (optional)"
        details:
          type: Markdown
          content: "Data field reference to evaluate for the condition that determines when the action should execute. Supports various conditional operators: `is`, `isNot`, `isEmpty`, `contains`, `containsNot`, `containedBy`, `containedByNot`, numeric comparisons (`>`, `<`, `>=`, `<=`), and complex conditions (`andConditions`, `orConditions`). For detailed information about each condition type, see the [conditional operators reference](#conditional-operators) below."

  - type: Markdown
    content: |
      In addition to these core properties, actions support action-specific properties that vary depending on the action type. For example, a `hide` action only requires the condition properties, while a `redirect` action needs a `to` property specifying the destination URL.

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: CheckBoxField
          dataLocation: ~.show_advanced
          options:
            - value: true
              label: "Show advanced settings"

        - type: div
          content: "Advanced Settings Panel"
          actions:
            - what: hide              # Action type
              when: ~.show_advanced    # Condition to evaluate
              isNot: true              # Expected value

  - type: RjBuildDescriber
    title: "Basic Action Demonstration"
    description:
      - type: Markdown
        content: |
          This example demonstrates how actions adapt the UI based on application state.
          
          When you check the checkbox, the "Advanced Settings Panel" becomes visible. The action continuously evaluates the condition and shows/hides content accordingly.

    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.show_advanced
          options:
            - value: true
              label: "Show advanced settings"

        - type: div
          content: "Basic Settings"
          attributes:
            style:
              padding: "15px"
              border: "2px solid var(--bs-border-color, #dee2e6)"
              borderRadius: "8px"
              margin: "10px 0"

        - type: div
          content: "Advanced Settings Panel"
          attributes:
            style:
              padding: "15px"
              border: "2px dashed var(--bs-border-color, #dee2e6)"
              borderRadius: "8px"
              margin: "10px 0"
              fontStyle: "italic"
          actions:
            - what: hide              # Action type
              when: ~.show_advanced    # Condition to evaluate
              isNot: true              # Expected value

      data:
        show_advanced: false

  - type: Markdown
    content: |
      ## Action Types

      Reactive-JSON provides several built-in actions:

      ### Visibility Control
      - **[hide](../core/action/Hide)**: Completely hides the element and its children
      - **[visuallyHide](../core/action/VisuallyHide)**: Visually hides the element while keeping it accessible to screen readers

      ### User Interaction
      - **[tooltip](../core/action/Tooltip)**: Displays a tooltip on hover
      - **[popover](../core/action/Popover)**: Shows a more complex popover on click

      ### Navigation
      - **[redirect](../core/action/Redirect)**: Redirects to a specified URL

      For detailed documentation of each action, including properties and examples, see their respective documentation pages.

  - type: RjBuildDescriber
    title: "Basic Conditional Actions"
    description:
      - type: Markdown
        content: |
          This example shows simple conditional actions using `is` and `isEmpty` conditions.

    toDescribe:
      renderView:
        - type: div
          content:
            - type: label
              content: "Status: "
            - type: SelectField
              dataLocation: ~.status
              options:
                - value: "inactive"
                  label: "Inactive"
                - value: "active"
                  label: "Active"
                  
            - type: br
            
            - type: label
              content: "Text: "
            - type: TextField
              dataLocation: ~.text_input
              placeholder: "Type something..."

        - type: div
          content:
            - type: div
              content: "This shows only when status is 'active'"
              attributes:
                style:
                  padding: "10px"
                  border: "1px solid var(--bs-border-color, #dee2e6)"
                  margin: "5px 0"
              actions:
                - what: hide
                  when: ~.status
                  isNot: "active"
                  
            - type: div
              content: "This shows only when text is not empty"
              attributes:
                style:
                  padding: "10px"
                  border: "1px solid var(--bs-border-color, #dee2e6)"
                  margin: "5px 0"
              actions:
                - what: hide
                  when: ~.text_input
                  isEmpty: true

      data:
        status: "inactive"
        text_input: ""

  - type: RjBuildDescriber
    title: "Tooltip Action Example"
    description:
      - type: Markdown
        content: |
          This example demonstrates the tooltip action with conditional display.

    toDescribe:
      renderView:
        - type: div
          content:
            - type: button
              content: "Hover for help (when enabled)"
              actions:
                - what: tooltip
                  content: "This is a helpful tooltip!"
                  placement: "top"
                  when: ~.show_tooltips
                  is: true
                  
            - type: br
            - type: br
            
            - type: label
              content:
                - type: CheckBoxField
                  dataLocation: ~.show_tooltips
                  options:
                    - value: true
                      label: ""
                - " Enable tooltips"

      data:
        show_tooltips: true

  - type: RjBuildDescriber
    title: "Practical Form Example"
    description:
      - type: Markdown
        content: |
          This example shows a simple form with conditional submit button and validation messages.

    toDescribe:
      renderView:
        - type: div
          content:
            - type: h4
              content: "Simple Contact Form"
              
            - type: div
              content:
                - type: label
                  content: "Name: "
                - type: TextField
                  dataLocation: ~.form.name
                  placeholder: "Enter your name"
                      
            - type: br
            
            - type: div
              content:
                - type: label
                  content: "Email: "
                - type: TextField
                  dataLocation: ~.form.email
                  inputType: "email"
                  placeholder: "Enter your email"
                      
            - type: br
            
            - type: div
              content: "Please fill in both fields"
              attributes:
                style:
                  color: "var(--bs-danger, #dc3545)"
                  fontSize: "14px"
              actions:
                - what: hide
                  andConditions:
                    - when: ~.form.name
                      isNotEmpty:
                    - when: ~.form.email
                      isNotEmpty:
                  
            - type: button
              content: "Submit"
              attributes:
                style:
                  border: "1px solid var(--bs-border-color, #dee2e6)"
                  padding: "8px 16px"
              actions:
                - what: hide
                  when: ~.form.name
                  isEmpty: true
                - what: hide
                  when: ~.form.email
                  isEmpty: true
                - what: setData
                  on: click
                  path: ~.submitted
                  value: true
                  
            - type: div
              content: "✅ Form submitted successfully!"
              attributes:
                style:
                  color: "var(--bs-success, #198754)"
                  marginTop: "10px"
                  fontWeight: "bold"
              actions:
                - what: hide
                  when: ~.submitted
                  isNot: true

      data:
        form:
          name: ""
          email: ""
        submitted: false

  - type: h2
    content: "Conditional Operators"
    attributes:
      id: conditional-operators

  - type: Markdown
    content: |
      Actions support the following conditional operators when using the `when` property:

  - type: DefinitionList
    content:
      - term:
          code: is
        details: "Value equals exactly the specified value."
      - term:
          code: isNot
        details: "Value is different from the specified value."
      - term:
          code: isEmpty
        details:
          type: Markdown
          content: "Value is empty (null, undefined, empty string, empty array, or empty object). The presence of the property is sufficient (value doesn't matter, can be `null` in JSON). Use `isEmpty:` to check if empty, or `isEmpty: \"not\"` to check if not empty (alternatively, use `isNotEmpty:`)."
      - term:
          code: isNotEmpty
        details:
          type: Markdown
          content: "Value is not empty (shorthand for `isEmpty: \"not\"`). The presence of the property is sufficient - the value doesn't matter and can be `null` in JSON."
      - term:
          code: contains
        details: "Value contains the specified substring or array element."
      - term:
          code: containsNot
        details: "Value does not contain the specified substring or array element."
      - term:
          code: containedBy
        details: "Value is contained within the specified array or string."
      - term:
          code: containedByNot
        details: "Value is not contained within the specified array or string."
      - term:
          code: ">"
        details: "Value is greater than the specified number or date."
      - term:
          code: "<"
        details: "Value is less than the specified number or date."
      - term:
          code: ">="
        details: "Value is greater than or equal to the specified number or date."
      - term:
          code: "<="
        details: "Value is less than or equal to the specified number or date."
      - term:
          code: andConditions
          after: " (array)"
        details:
          type: Markdown
          content: |
            All nested conditions must be true for the action to execute.
            
            ```yaml
            # Example: Hide when both status is active AND user has admin role
            andConditions:
              - when: ~.status
                is: "active"
              - when: ~.user_role
                is: "admin"
            ```
      - term:
          code: orConditions
          after: " (array)"
        details: "At least one nested condition must be true for the action to execute."

  - type: Markdown
    content: |

      ## Execution Order
      - Actions are evaluated in the order they appear in the array.
      - Conditions are evaluated before action execution.
      - Some actions (like `hide`) prevent subsequent actions from executing.

      ## State-Driven Behavior
      - Actions continuously evaluate their conditions based on current data.
      - No explicit triggers needed - they respond automatically to data changes.
      - Perfect for creating adaptive interfaces that respond to application state.

  - type: Markdown
    content: |
      ## Technical Limitations

      1. **Execution order**: Actions are evaluated in definition order and cannot be reordered dynamically.
      2. **Hide behavior**: Once an element is hidden with the `hide` action, no subsequent actions execute.
      3. **Synchronous evaluation**: All conditions and actions are evaluated synchronously.
      4. **Data scope**: Actions can only access data from the current template context and global context.
      5. **No side effects**: Actions cannot directly modify global state or trigger reactions.
      6. **External dependencies**: Some actions (tooltip, popover) require React Bootstrap components.

      ## Best Practices

      1. **Keep conditions simple**: Avoid overly complex condition logic for better maintainability.
      2. **Consider performance**: Minimize frequently-evaluated complex conditions.
      3. **Use appropriate actions**: Choose `visuallyHide` over `hide` when content should remain accessible.
      4. **Test thoroughly**: Verify action behavior with different data states.
      5. **Document complex logic**: Add comments for non-obvious conditional logic.
      6. **Order matters**: Place critical actions (like `hide`) early in the action array when appropriate.

      ## Next Steps

      Now that you understand how actions work to adapt the UI based on application state, learn about **[Reactions](./reactions)** to handle user events and trigger behaviors in response to user interactions.

      Actions and reactions work together to create fully interactive applications: actions provide state-driven UI adaptation, while reactions enable event-driven behavior.

      ## Related Documentation

      - **[Reactions System](./reactions)**: Learn about handling user events and state changes.
      - **[Template System](../getting-started/template-contexts-data-binding)**: Understand data binding and template expressions.