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

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

renderView:
  - type: Markdown
    content: |
      # RjBuild File Structure

      ## What is an RjBuild?

      An **RjBuild** is the standard file format used by Reactive-JSON to build interactive web applications. It is a JSON or YAML structure that completely describes a user interface, its data, and behavior, without requiring traditional JavaScript code.

      > By extension, we also call "RjBuild" any fragment of this structure, particularly a portion of `renderView` and `templates` that can be reused or included in other RjBuilds.

      ### Supported Formats

      An RjBuild can be written in two formats:

      - **YAML** (recommended): More readable and easier to write for humans, ideal for creation and maintenance
      - **JSON**: Standard supported format, useful for programmatic generation or integration with existing tools

      **YAML is preferable** for most use cases as it offers better readability, allows comments, and is more tolerant of minor syntax errors.

      ## Basic Structure of an RjBuild

      Any RjBuild file can contain up to four main sections:

      - `renderView`: User interface structure (required)
      - `templates`: Reusable components (optional)
      - `data`: Initial state and data (optional)
      - `additionalDataSource`: External data sources (optional)

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:           # User interface structure (required)
        - type: div
          content: "Hello World"
      
      templates:            # Reusable components (optional)
        myComponent:
          type: div
          content: "Template content"
      
      data:                 # Initial state and data (optional)
        message: "Welcome!"
        user:
          name: "John"
      
      additionalDataSource: # External data sources (optional)
        - src: "/api/data.json"
          path: ~~.dynamicData

  - type: Markdown
    content: |

      ## Section `renderView` (Required)

      The `renderView` section defines the **user interface** that will be displayed. It is the only required section of an RjBuild.

      ### Role
      - Determines the visual structure of the application
      - Defines the components to display and their organization
      - Specifies interactions and behaviors

      ### Structure

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: ComponentName    # Type of component to render
          content: "Content"     # Component content
          attributes:            # HTML attributes (optional)
            class: "css-class"
          actions:               # Interactive actions (optional)
            - what: hide
              on: click

  - type: Markdown
    content: |

      ### Examples

      #### Simple interface

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: div
          content: 
            - type: h1
              content: "My Application"
            - type: p
              content: "Welcome!"

  - type: Markdown
    content: |

      #### With dynamic data
      
  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: div
          content: ["Hello ", ~~.user.name, "!"]
      
      data:
        user:
          name: "Marie"

  - type: Markdown
    content: |
      ### Arrays in Content vs. Attributes

      - Arrays are supported in `content` to render multiple text nodes or elements in sequence (they are not string concatenations).
      - Do not use arrays inside HTML attributes (e.g., `href`, `class`, `id`). Attributes expect a single value. If you need a composed value, compute it beforehand and pass the final string.

      Example (valid):
      ```yaml
      content: ["Go to ", ~.sectionName]
      ```

      Example (invalid in attributes):
      ```yaml
      # ❌ Do not do this
      attributes:
        href: ["#", ~.id]
      ```

      Instead, prepare the value upstream:
      ```yaml
      # ✅ Provide a ready-to-use attribute value
      attributes:
        href: ~.href  # where href is a string like "#section-3"
      ```

  - type: Markdown
    content: |

      ## Section `data` (Optional)

      The `data` section contains the **initial state** of the application. This data can be read and modified by components.

      ### Role
      - Provides the initial state of the application
      - Stores data modifiable by user interactions
      - Enables data sharing between components

      ### Structure

  - type: TabbedSerializer
    yamlSerializedContent: |
      data:
        # Simple data
        title: "My Site"
        isLoggedIn: false
        
        # Objects
        user:
          name: "John"
          email: "john@example.com"
          
        # Arrays
        items:
          - name: "Item 1"
            active: true
          - name: "Item 2" 
            active: false

  - type: Markdown
    content: |
      ### Data Access

      To use data in a component, you can use the following syntax:

      - **`~~.`**: Global access to data from anywhere in the RjBuild
      - **`~.`**: Local access to data from the current context (template)

      ### Usage Examples

      #### Forms with state

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: TextField
          label: "Name"
          dataLocation: ~~.user.name
        - type: div
          content: ["Entered name: ", ~~.user.name]

      data:
        user:
          name: "Initial value"

  - type: Markdown
    content: |

      #### Conditional display

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: div
          content: "User is logged in!"
          actions:
            - what: hide
              when: ~~.isLoggedIn
              is: false

      data:
        isLoggedIn: true

  - type: Markdown
    content: |
      > You can get more information about data access in the [template system documentation](/docs/getting-started/template-contexts-data-binding).

      ## Section `templates` (Optional)

      The `templates` section defines **reusable components** that can be used in `renderView` or other templates.

      ### Role
      - Avoids code duplication
      - Enables reuse of complex structures
      - Facilitates maintenance and modifications

      ### Structure

  - type: TabbedSerializer
    yamlSerializedContent: |
      templates:
        templateName:         # Template name
          type: ComponentName # Template structure
          content: "Content"
          
        multipleComponents:   # Template with multiple components
          - type: div
            content: "Component 1"
          - type: p
            content: "Component 2"

  - type: Markdown
    content: |

      ### Using templates

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - load: templateName  # Loads and displays the template

      templates:
        templateName:
          type: div
          content: "I am a reusable template!"

  - type: Markdown
    content: |

      ### Data Context
      Templates create their own **data context** when used with components like `Switch`:

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: Switch
          content: ~~.users        # Iterates over each user
          singleOption:
            load: userCard        # Each user uses the template

      templates:
        userCard:
          type: div
          content:
            - "Name: "
            - ~.name              # Local access to current user's name
            - " (Admin: "
            - ~~.isAdmin          # Global access to settings

      data:
        isAdmin: true
        users:
          - name: "Alice"
          - name: "Bob"

  - type: Markdown
    content: |

      ## Section `additionalDataSource` (Optional)

      The `additionalDataSource` section allows **loading data from external sources** during application initialization.

      ### Role
      - Integrates dynamic data from APIs
      - Enables asynchronous data loading
      - Separates static data from dynamic data

      ### Structure

  - type: TabbedSerializer
    yamlSerializedContent: |
      additionalDataSource:
        - src: "/api/endpoint"    # Source URL (required)
          path: ~~.targetPath     # Where to place the data (optional)
          method: GET             # HTTP method (optional, default: GET)
          blocking: true          # Block rendering (optional, default: false)

  - type: Markdown
    content: |

      ### Properties
      - **`src`** (required): URL of the data source
      - **`path`** (optional): Path where to place the data (template syntax)
      - **`method`** (optional): HTTP method (GET, POST, etc.)
      - **`dataMapping`** (optional): Configure selective data dispatch using mapping processors
      - **`blocking`** (optional): If `true`, waits for loading before displaying

      ### Loading Modes

      #### Blocking loading

  - type: TabbedSerializer
    yamlSerializedContent: |
      additionalDataSource:
        - src: "/api/user-profile.json"
          path: ~~.currentUser
          blocking: true          # Page waits for loading

  - type: Markdown
    content: |

      #### Non-blocking loading

  - type: TabbedSerializer
    yamlSerializedContent: |
      additionalDataSource:
        - src: "/api/notifications.json"
          path: ~~.notifications
          blocking: false         # Page displays immediately

  - type: Markdown
    content: |

      ### Data Placement

      #### With specific path

  - type: TabbedSerializer
    yamlSerializedContent: |
      additionalDataSource:
        - src: "/api/user.json"
          path: ~~.currentUser
          
      # Data will be placed in data.currentUser

  - type: Markdown
    content: |

      #### Root-level merge

  - type: TabbedSerializer
    yamlSerializedContent: |
      additionalDataSource:
        - src: "/api/config.json"
          # No path = direct merge into data

  - type: Markdown
    content: |

      ### Data Mapping Integration

      Data Mapping can be used with `additionalDataSource` to selectively dispatch response data to specific locations:

  - type: TabbedSerializer
    yamlSerializedContent: |
      additionalDataSource:
        - src: "/api/user-profile"
          blocking: true
          dataMapping:
            simpleMapping:
              stringMap:
                "profile.displayName": { value: "user.name" }
                "profile.email": { value: "user.email" }
                "settings.theme": 
                  value: "user.preferences.theme"
                  required: false
                  defaultValue: "light"

  - type: Markdown
    content: |

      **Note**: When `dataMapping` is configured, it takes priority over the `path` property. For more details, see [Data Mapping Documentation](../advanced-concepts/data-mapping).

      ### Complete Example

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: div
          content:
            - type: h1
              content: ["Hello ", ~~.currentUser.name]
            - type: p
              content: ["Version: ", ~~.systemConfig.version]

      data:
        currentUser:
          name: "Loading..."    # Temporary value
        systemConfig:
          version: "Loading..."

      additionalDataSource:
        # Critical user data (blocking)
        - src: "/api/user-profile.json"
          path: ~~.currentUser
          blocking: true
          
        # System configuration (non-blocking)
        - src: "/api/system-config.json"
          path: ~~.systemConfig
          blocking: false

  - type: Markdown
    content: |

      ## Best Practices

      ### Organization
      1. **Logical structure**: Organize your data by functional domain
      2. **Reusable templates**: Create templates to avoid duplication
      3. **Default values**: Provide temporary values for external data

      ### Performance
      1. **Smart loading**: Use `blocking: true` only for critical data
      2. **Minimal data**: Load only necessary data
      3. **Optimized templates**: Avoid overly complex templates

      ### Maintainability
      1. **Consistent naming**: Use clear conventions for templates and data.
      2. **Documentation**: Comment complex sections.
      3. **Validation**: Verify the structure of your external data.

      ## Next Steps

      Now that you understand the structure of RjBuilds, learn about the **[Template System](./template-contexts-data-binding)** to master data binding and create reusable components.

      The template system is crucial for building maintainable and dynamic applications with Reactive-JSON.

templates:

data: