@ea-lab/reactive-json-docs/public/rjbuild/docs/getting-started/template-contexts-data-binding.yaml

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

renderView:
  - type: Markdown
    content: |
      # Template, Contexts, and Data Binding

      The template system in reactive-json efficiently manages data contexts and their access. Understanding how templates "containerize" data is essential for properly using components, actions, and reactions.

      ## Context Notations

      There are four main notations for accessing data:
      
      - `~.` : Local context (relative to current template)
      - `~~.` : Global context (access to global data)
      - `~>key` : Finds the nearest "key" by going up the hierarchy (useful when multiple keys exist)
      - `~~>key` : Finds the top-level "key" from root (useful for global settings)

      Each notation is explained with examples below.

  - type: RjBuildDescriber
    title:
      type: Markdown
      content: "Local Context: `~.`"
    description:
      - type: Markdown
        content: |
          Accesses data from the current template context.

    toDescribe:
      renderView:
        - type: div
          content: ["Hello ", ~.username]  # Accesses username from current context

      data:
        username: "John"

  - type: RjBuildDescriber
    title:
      type: Markdown
      content: "Global Context: `~~.`"
    description:
      - type: Markdown
        content: |
          Accesses data from the global (root) data, regardless of current template context.

    toDescribe:
      templates:
        userCard:
          - type: div
            content:
              - "Admin: "
              - type: LabelFromValue
                dataLocation: ~~.isAdmin  # Accesses isAdmin from global data
                options:
                  - label: "Yes"
                    value: true
                  - label: "No"
                    value: false

      renderView:
        - load: userCard

      data:
        isAdmin: true

  - type: RjBuildDescriber
    title:
      type: Markdown
      content: "Nearest Key: `~>key`"
    description:
      - type: Markdown
        content: |
          Searches for "key" by going up the hierarchy, finds the nearest occurrence.

    toDescribe:
      templates:
        themeDisplay:
          type: div
          content: ["Theme: ", ~>config.theme]  # Gets theme from nearest config

      renderView:
        - type: Switch
          content: ~~.config.userSection.config.items
          singleOption:
            load: themeDisplay

      data:
        config:
          theme: "dark"
          userSection:
            config:
              theme: "light"   # This will be found (nearest)
              items:
                - name: "Item 1"  # themeDisplay template runs here

  - type: RjBuildDescriber
    title:
      type: Markdown
      content: "Top-level Key: `~~>key`"
    description:
      - type: Markdown
        content: |
          Searches for "key" starting from root, finds the top-level occurrence.

    toDescribe:
      templates:
        themeDisplay:
          type: div
          content: ["Theme: ", ~~>config.theme]  # Gets theme from top-level config

      renderView:
        - type: Switch
          content: ~~.config.userSection.config.items
          singleOption:
            load: themeDisplay

      data:
        config:
          theme: "dark"      # This will be found (top-level)
          userSection:
            config:
              theme: "light"
              items:
                - name: "Item 1"  # themeDisplay template runs here

  - type: Markdown
    content: |
      ## Containerization Principle

      Templates create context "containers". This means each template defines its own local data space.

      ### Impact on Components

      This containerization affects several aspects:

      1. **Forms**: Form fields using `~.` access data from their defining template
      2. **Actions**: Actions using `~.` modify data within the template context
      3. **Reactions**: Reactions can access different levels depending on the prefix used

  - type: RjBuildDescriber
    title: "Form Context Example"
    description:
      - type: Markdown
        content: |
          This example shows how a form uses local context for editing before saving to the global context.

    toDescribe:
      templates:
        editForm:
          type: form
          content:
            - type: TextField
              path: ~.temp_name  # Local modification
              value: ~.name      # Initial value
            - type: button
              content: "Save"
              actions:
                - what: setData
                  on: click
                  path: ~~.globalUser.name  # Global save
                  value: ~.temp_name        # Uses temporary value

      data:
        temp_name: ""
        name: "John"
        globalUser:
          name: "John"

  - type: Markdown
    content: |
      ## Key Points to Remember

      1. Two components using `~.` in different templates access different data
      2. Actions and reactions respect the context where they are defined
      3. Containerization allows isolating modifications until validation
      4. `~~.` allows "escaping" the container to access global data
      5. `~>key` finds the nearest "key" by going up step by step (useful for local overrides)
      6. `~~>key` finds the top-level "key" from root (useful for global settings)

      ## Best Practices

      1. **Context Coherence**: Ensure components that need to share data are in the same context
      2. **Global Access**: Use `~~.` for data that needs to be shared between different templates
      3. **Hierarchical Navigation**: Use `~>key` to find nearest occurrence or `~~>key` to find global setting
      4. **Local vs Global**: `~>` prioritizes local overrides, `~~>` prioritizes global settings

  - type: RjBuildDescriber
    title: "Complete Practical Example"
    description:
      - type: Markdown
        content: |
          Here's a complete working example that demonstrates all four syntaxes in action with a functional renderView.

    toDescribe:
      data:
        global_value: "Hello"
        config:
          theme: "dark"
          userSection:
            title: "User List"
            config:
              theme: "light"
              level1:
                items:
                  - name: "Item 1"
                  # userList template instances run here at: data.config.userSection.config.level1.items

      templates:
        userList:
          type: div
          content:
            - type: div
              content: ["Global: ", ~~.global_value]        # From root data
            - type: div  
              content: ["Local: ", ~.name]                  # From current template
            - type: div
              content: ["Theme (nearest): ", ~>config.theme]    # Get from nearest config → "light"
            - type: div
              content: ["Theme (global): ", ~~>config.theme]   # Get from top-level config → "dark"

      renderView:
        - type: Switch
          content: ~~.config.userSection.config.level1.items
          singleOption:
            load: userList

  - type: Markdown
    content: |
      ## Next Steps

      Now that you understand the template system and data binding, learn about **[Actions](./actions)** to make your interfaces interactive and responsive to data changes.

      Actions will allow you to hide, show, and manipulate elements based on the current application state.

templates:

data: {}