@ea-lab/reactive-json-docs
Version:
Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides
396 lines (359 loc) • 13.1 kB
YAML
renderView:
- type: Markdown
content: |
# SimpleMapping Data Mapper
SimpleMapping is the core data mapping processor in Reactive-JSON that enables selective dispatch and transformation of HTTP response data to specific locations in your application state.
## Basic Syntax
- type: TabbedSerializer
yamlSerializedContent: |
dataMapping:
simpleMapping:
stringMap:
"~~.app.data.path":
value: "response.data.path"
required: true
defaultValue: "fallback"
updateMode: "replace"
onErrorMap:
"~~.error.path":
value: "Error message or ~~.template.reference"
- type: Markdown
content: |
## Properties
- type: DefinitionList
content:
- term:
code: stringMap
after: " (object, required)"
details:
- type: Markdown
content: |
The `stringMap` configuration is used to map source paths in the HTTP response to specific locations in your application state.
Each key in the `stringMap` object represents a destination path in your application state, e.g. `~~.profile.displayName`.
The value associated with each key is an object that defines how to map the source data to that destination.
Here is the list of properties that can be used in the value object:
- type: DefinitionList
content:
- term:
code: value
after: " (required)"
details:
type: Markdown
content: |
Source path in the HTTP response (e.g., `user.firstName`).
- term:
code: required
after: " (optional, default: true)"
details:
type: Markdown
content: |
Whether the source value must exist.
- term:
code: defaultValue
after: " (optional)"
details:
type: Markdown
content: |
Fallback value when source is missing and not required.
- term:
code: updateMode
after: " (optional, default: \"replace\")"
details:
type: Markdown
content: |
How to apply the value (`"replace"`, `"add"`, `"move"`, `"remove"`).
- type: DefinitionList
content:
- term:
code: onErrorMap
after: " (object, optional)"
details:
- type: Markdown
content: |
The `onErrorMap` works like `stringMap`, but provides fallback values when main mappings fail.
Same key-value structure as `stringMap` (destination → configuration).
Applied only when corresponding `stringMap` entries fail and are marked as `required: true`.
Here is the list of properties that can be used in the value object:
- type: DefinitionList
content:
- term:
code: value
after: " (required)"
details:
type: Markdown
content: |
Can be either static values (e.g., `Error occurred`) or template references (e.g., `~~.errorTimestamp`).
- type: Markdown
content: |
## Live Example
- type: RjBuildDescriber
title: "Basic Data Mapping Example"
description:
- type: Markdown
content: |
This example demonstrates how to map API response fields to specific locations in your application state using the simpleMapping processor.
toDescribe:
renderView:
- type: div
attributes:
class: "mb-4"
content:
- type: Markdown
content: "**Simulated API Response:**"
- type: TabbedSerializer
yamlSerializedContent: |
user:
firstName: "John"
lastName: "Doe"
email: "john@example.com"
preferences:
theme: "dark"
language: "en"
notifications: true
profile:
avatar: "/images/john-avatar.png"
bio: "Software developer passionate about React and data processing"
metadata:
requestId: "req_12345"
timestamp: "2024-01-15T10:30:00Z"
version: "v1.2.3"
status: "success"
- type: BsButton
content: "Simulate API Call with Data Mapping"
attributes:
class: "btn btn-primary mb-3"
actions:
- what: fetchData
on: click
url: "/mockup-api/fetchData/data-mapping-example.json"
updateOnlyData: true
dataMapping:
simpleMapping:
stringMap:
"~~.profile.displayName":
value: "user.firstName"
"~~.profile.email":
value: "user.email"
"~~.settings.theme":
value: "user.preferences.theme"
required: false
defaultValue: "light"
"~~.settings.language":
value: "user.preferences.language"
required: false
defaultValue: "en"
"~~.profile.fullName":
value: "user.fullName"
required: false
defaultValue: "Anonymous User"
- type: Markdown
content: |
**Current Application State (after mapping):**
- type: div
attributes:
class: "card mb-3"
content:
- type: div
attributes:
class: "card-header"
content: "Profile Data"
- type: div
attributes:
class: "card-body"
content:
- type: p
content:
- "Display Name: "
- type: strong
content: ~~.profile.displayName
- type: p
content:
- "Email: "
- type: strong
content: ~~.profile.email
- type: p
content:
- "Full Name: "
- type: strong
content: ~~.profile.fullName
- type: div
attributes:
class: "card"
content:
- type: div
attributes:
class: "card-header"
content: "Settings Data"
- type: div
attributes:
class: "card-body"
content:
- type: p
content:
- "Theme: "
- type: span
attributes:
class: "badge bg-primary"
content: ~~.settings.theme
- type: p
content:
- "Language: "
- type: span
attributes:
class: "badge bg-secondary"
content: ~~.settings.language
data:
profile: {}
settings: {}
- type: RjBuildDescriber
title: "Error Handling with onErrorMap"
description:
- type: Markdown
content: |
This example shows how to provide fallback values when required data fields are missing from the API response, demonstrating graceful error handling.
toDescribe:
renderView:
- type: div
attributes:
class: "mb-3"
content:
- type: Markdown
content: |
**API Response (missing user data):**
```json
{
"status": "ok",
"timestamp": "2024-06-01T12:00:00Z"
}
```
The mapping below tries to extract `user.name` and `user.email` which don't exist in this response, triggering the `onErrorMap` fallback values.
- type: BsButton
content: "Test Missing Data Handling"
attributes:
class: "btn btn-warning mb-3"
actions:
- what: fetchData
on: click
url: "/mockup-api/fetchData/status.json"
updateOnlyData: true
dataMapping:
simpleMapping:
stringMap:
"~~.profile.name":
value: "user.name"
required: true
"~~.profile.email":
value: "user.email"
required: true
"~~.profile.department":
value: "user.department"
required: false
defaultValue: "No department"
onErrorMap:
"~~.profile.status":
value: "Error loading profile"
"~~.profile.name":
value: "Unknown User"
"~~.profile.email":
value: "unknown@example.com"
"~~.profile.loadedAt":
value: "~~.currentTimestamp"
- type: Markdown
content: |
**Profile State (after error handling):**
- type: div
attributes:
class: "card"
content:
- type: div
attributes:
class: "card-header"
content: "Profile Data"
- type: div
attributes:
class: "card-body"
content:
- type: p
content:
- "Status: "
- type: span
attributes:
class: "badge bg-warning"
content: ~~.profile.status
- type: p
content:
- "Name: "
- type: strong
content: ~~.profile.name
- type: p
content:
- "Email: "
- type: strong
content: ~~.profile.email
- type: p
content:
- "Loaded At: "
- type: em
content: ~~.profile.loadedAt
data:
profile: {}
currentTimestamp: "2024-01-15T10:30:00Z"
- type: Markdown
content: |
## Advanced Configuration Examples
### Complex Data Structure Mapping
- type: TabbedSerializer
yamlSerializedContent: |
dataMapping:
simpleMapping:
stringMap:
"~~.currentOrder.id":
value: "order.id"
"~~.currentOrder.customerName":
value: "order.customer.name"
"~~.currentOrder.customerEmail":
value: "order.customer.contact.email"
"~~.currentOrder.total":
value: "order.billing.total"
"~~.currentOrder.currency":
value: "order.billing.currency"
required: false
defaultValue: "USD"
- type: Markdown
content: |
### Integration with additionalDataSources
- 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: |
### Integration with Template Context
- type: TabbedSerializer
yamlSerializedContent: |
dataMapping:
simpleMapping:
stringMap:
"~~.pagination.currentPage":
value: "meta.page"
required: false
defaultValue: "~~.pagination.page" # Use current page as default
- type: Markdown
content: |
## About the Data Mapping System
For information about the broader Data Mapping system and how to create custom mappers, see the **[Data Mapping Overview](../../advanced-concepts/data-mapping)**.
templates:
data:
profile: {}
settings: {}
currentTimestamp: "2024-01-15T10:30:00Z"