@ea-lab/reactive-json-docs/public/rjbuild/docs/core/reaction/fetchData.yaml

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

renderView:
  - type: Markdown
    content: |
      # fetchData

      `fetchData` is a reaction that allows making HTTP requests to a server. It operates in multiple modes, depending on configuration values.

      - Supports configurable HTTP methods (GET by default for backward compatibility)
      - Only one request can be active at a time
      - The URL is evaluated via the template system before sending, but must resolve to a static string
      - The response can refresh the app (default) or be ignored

      ## Properties

  - type: DefinitionList
    content:
      - term:
          code: httpMethod
          after: "(string, optional)"
        details:
          type: Markdown
          content: "The HTTP method to use (default: \"get\"). Supports: get, post, put, patch, delete, etc."
      - term:
          code: refreshAppOnResponse
          after: "(boolean, optional)"
        details:
          type: Markdown
          content: "If true (default), the response will update the application. If false, the response is ignored (webhook mode)"
      - term:
          code: updateDataAtLocation
          after: "(string, optional)"
        details:
          type: Markdown
          content: "When `updateOnlyData` is true, specifies where to place the response data using template path syntax (e.g., \"~~.userProfile\", \"~.config.settings\"). If not specified, replaces the entire data object"
      - term:
          code: updateOnlyData
          after: "(boolean, optional)"
        details:
          type: Markdown
          content: "When true and `refreshAppOnResponse` is true, only updates the data section instead of replacing the entire RjBuild. Preserves templates and renderView. Default: false"
      - term:
          code: url
          after: "(string, required)"
        details:
          type: Markdown
          content: "The URL to call (must be a static string, dynamic URLs are not supported)"

  - type: Markdown
    content: |
      ## Behavior
      - Supports configurable HTTP methods (GET by default for backward compatibility)
      - Only one request can be active at a time
      - The URL is evaluated via the template system before sending, but must resolve to a static string
      - If `refreshAppOnResponse` is true, the response must be a valid rjbuild and will replace the application state
      - If `refreshAppOnResponse` is false, the response is ignored (webhook mode)
      - Errors are only logged to the console
      - The triggering element is visually disabled during the request

  - type: RjBuildDescriber
    title: Basic Structure (GET - Default)
    description:
      - type: Markdown
        content: |
          The basic structure of a fetchData reaction requires a URL and can include the refreshAppOnResponse option.

          The URL can be a template value that resolves to a static string. By default, fetchData uses GET method.
    toDescribe:
      renderView:
        - type: button
          content: Basic GET Example
          actions:
            - what: fetchData
              on: click
              url: "/mockup-api/fetchData/example.json"
              refreshAppOnResponse: true  # Response will replace the application state
        - type: div
          content:
            - "URL: "
            - "/mockup-api/fetchData/example.json"
        - type: div
          content:
            - "Method: GET (default)"
        - type: div
          content:
            - "Fetch status: "
            - ~.fetch_status
      data:
        fetch_status: "Waiting for click"

  - type: RjBuildDescriber
    title: Custom HTTP Methods
    description:
      - type: Markdown
        content: |
          You can specify different HTTP methods using the `httpMethod` property:
          - GET (default)
          - POST, PUT, PATCH, DELETE
          - Any valid HTTP method

          > Open the console to see the request details.
    toDescribe:
      renderView:
        - type: button
          content: PATCH Request
          actions:
            - what: fetchData
              on: click
              url: "/mockup-api/fetchData/status.json"
              httpMethod: "patch"
              refreshAppOnResponse: false
        - type: button
          content: DELETE Request
          actions:
            - what: fetchData
              on: click
              url: "/mockup-api/fetchData/status.json"
              httpMethod: "delete"
              refreshAppOnResponse: false
        - type: div
          content:
            - "Custom methods: PATCH, DELETE, etc."
      data:
        method_status: "Ready to test"

  - type: RjBuildDescriber
    title: Webhook Mode
    description:
      - type: Markdown
        content: |
          With `refreshAppOnResponse: false`, fetchData behaves like a webhook:
          - Response is completely ignored
          - Only the HTTP call is made
          - Works with any HTTP method
          - Useful for:
            * Server notifications
            * Triggering server-side actions
            * API pinging
            * Sending webhooks
            * Cache invalidation
            * Remote resource cleanup
    toDescribe:
      renderView:
        - type: button
          content: Notify Server (POST)
          actions:
            - what: fetchData
              on: click
              url: "/mockup-api/fetchData/status.json"
              httpMethod: "post"
              refreshAppOnResponse: false  # Response is ignored, like a webhook
        - type: div
          content:
            - "Last call: "
            - ~.last_status
      data:
        last_status: "Not made"

  - type: RjBuildDescriber
    title: Error Handling
    description:
      - type: Markdown
        content: |
          Errors are logged to the console but don't trigger a reload.

          The triggering element is visually disabled during the request.

          **Limitation**: No built-in error handling beyond console logging.
    toDescribe:
      renderView:
        - type: button
          content: Test Error
          actions:
            - what: fetchData
              on: click
              url: "/mockup-api/fetchData/error.json"
        - type: div
          content:
            - "Status: "
            - ~.error_state
      data:
        error_state: "Pending"

  - type: RjBuildDescriber
    title:
      type: Markdown
      content: |
        Data-Only Update Examples `@ea-lab/reactive-json@0.2.0`
    description:
      - type: Markdown
        content: |
          Properties `updateOnlyData` and `updateDataAtLocation` (added in @ea-lab/reactive-json@0.2.0) allow for more precise data management:
          
          - `updateOnlyData: true`: Only updates the data section, preserving templates and renderView
          - `updateDataAtLocation`: Specifies exactly where to place the response data
          
          
          > **⚠️ Important:** When using `updateOnlyData: true`, the server must return **data only**, not a complete RjBuild structure.
    toDescribe:
      additionalDataSource:
        - src: "/mockup-api/fetchData/reset-initial-data.json"
      renderView:
        - type: div
          attributes:
            class: "row mb-3"
          content:
            - type: div
              attributes:
                class: "col-md-6"
              content:
                - type: BsButton
                  content: "Complete Data Replacement"
                  attributes:
                    class: "btn btn-primary mb-2 w-100"
                  actions:
                    - what: fetchData
                      on: click
                      url: "/mockup-api/fetchData/complete-replacement.json"
                      updateOnlyData: true
                      refreshAppOnResponse: true
                
                - type: BsAlert
                  attributes:
                    variant: "info"
                    class: "small"
                  content: "⚠️ Replaces ALL data (userProfile + settings + status)"
            
            - type: div
              attributes:
                class: "col-md-6"
              content:
                - type: BsButton
                  content: "Targeted Data Update"
                  attributes:
                    class: "btn btn-secondary mb-2 w-100"
                  actions:
                    - what: fetchData
                      on: click
                      url: "/mockup-api/fetchData/user-profile-update.json"
                      updateOnlyData: true
                      updateDataAtLocation: "~~.userProfile"
                      refreshAppOnResponse: true
                
                - type: BsAlert
                  attributes:
                    variant: "success"
                    class: "small"
                  content: "✅ Updates ONLY userProfile, preserves settings"

        - type: div
          attributes:
            class: "text-center mb-3"
          content:
            - type: BsButton
              content: "🔄 Reset to Initial Data"
              attributes:
                class: "btn btn-secondary"
              actions:
                - what: fetchData
                  on: click
                  url: "/mockup-api/fetchData/reset-initial-data.json"
                  updateOnlyData: true
                  refreshAppOnResponse: true

        - type: hr

        - type: div
          attributes:
            class: "row"
          content:
            - type: div
              attributes:
                class: "col-md-4"
              content:
                - type: h6
                  content: "👤 User Profile"
                - type: div
                  attributes:
                    class: "border p-2 rounded bg-primary bg-opacity-10 small"
                  content:
                    - type: div
                      content:
                        - type: strong
                          content: "Name: "
                        - ~~.userProfile.name
                    - type: div
                      content:
                        - type: strong
                          content: "Email: "
                        - ~~.userProfile.email
                    - type: div
                      content:
                        - type: strong
                          content: "Updated: "
                        - ~~.userProfile.lastUpdated
            
            - type: div
              attributes:
                class: "col-md-4"
              content:
                - type: h6
                  content: "⚙️ Settings"
                - type: div
                  attributes:
                    class: "border p-2 rounded bg-light small"
                  content:
                    - type: div
                      content:
                        - type: strong
                          content: "Theme: "
                        - ~~.settings.theme
                    - type: div
                      content:
                        - type: strong
                          content: "Notifications: "
                        - ~~.settings.notifications
                    - type: div
                      content:
                        - type: strong
                          content: "Language: "
                        - ~~.settings.language
            
            - type: div
              attributes:
                class: "col-md-4"
              content:
                - type: h6
                  content: "📊 Status"
                - type: div
                  attributes:
                    class: "border p-2 rounded bg-warning bg-opacity-10 small"
                  content:
                    - type: div
                      content:
                        - type: strong
                          content: "Online: "
                        - ~~.status.online
                    - type: div
                      content:
                        - type: strong
                          content: "Last Login: "
                        - ~~.status.lastLogin

        - type: div
          attributes:
            class: "mt-3 alert alert-warning"
          content:
            - type: strong
              content: "How to test:"
            - " Click buttons and watch the data sections above. The first button will replace ALL data, the second will only update the User Profile section."
 
  - type: Markdown
    content: |
      ## Limitations

      - Only one request can be active at a time
      - Response must be a valid rjbuild **only** if refreshAppOnResponse is true
      - No built-in error handling beyond console logging
      - No support for request cancellation
      - No support for timeouts
      - **No support for dynamic URLs** - URLs must be static strings
      - No support for query parameters in URL templates
      - No support for complex URL routing or path generation
      - **No request body support** - Use `submitData` if you need to send data in the request body

  - type: Markdown
    content: |
      ## Styling Fetching State (CSS)
      You can visually disable form controls during a fetchData request using CSS. The system is the same as for submitData:

      ### 1. Target only the fetching control (button, input, etc.)
      The element that triggered the fetch receives `data-is-submitting="true"` during the request:

      ```css
      input[data-is-submitting="true"],
      button[data-is-submitting="true"],
      select[data-is-submitting="true"],
      textarea[data-is-submitting="true"] {
        opacity: 0.5;
        pointer-events: none;
        cursor: not-allowed;
      }
      ```

      ### 2. Target all controls globally during fetch
      While a fetch is in progress, the `<body>` receives `data-html-builder-is-submitting="true"`. You can use this to disable all form controls:

      ```css
      body[data-html-builder-is-submitting="true"] input,
      body[data-html-builder-is-submitting="true"] button,
      body[data-html-builder-is-submitting="true"] select,
      body[data-html-builder-is-submitting="true"] textarea {
        opacity: 0.5;
        pointer-events: none;
        cursor: not-allowed;
      }
      ```

      Choose the approach that best fits your UX needs.