@ea-lab/reactive-json-docs/public/rjbuild/docs/advanced-concepts/attribute-transformers.yaml

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

renderView:
  - type: Markdown
    content: |
      # Attribute Transformers

      > **Note**: Reactive-JSON provides two systems for attribute modification:
      > 
      > - **Attribute Transformers** (this section): Execute **before rendering**, modify attributes for child components
      > - **[Attribute Actions](../core/action/Attribute/index)**: Execute **after rendering**, modify DOM attributes directly
      > 
      > Choose transformers for pre-render attribute conditioning and actions for post-render DOM manipulation.

      Attribute Transformers in Reactive-JSON allow you to modify element attributes before rendering based on dynamic conditions. They are evaluated during the attribute evaluation phase and provide pre-render attribute manipulation capabilities.

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: div
          attributes:
            class: "base-class"
            data-status: "default"
          attributeTransforms:
            # Add class conditionally
            - what: setAttributeValue
              name: "class"
              value: "active"
              when: ~~.isActive
              is: true
            
            # Remove attribute entirely
            - what: unsetAttribute
              name: "data-status"
              when: ~~.hideStatus
              is: true
            
            # Toggle between states
            - what: toggleAttributeValue
              name: "class"
              value: ["theme-light", "theme-dark"]
              when: ~~.toggleTheme
              isNotEmpty:

  - type: Markdown
    content: |
      ## Key Differences from Actions

      - **Timing**: Attribute transformers execute **before rendering**, while actions execute **after rendering**
      - **Impact**: Transformers affect attributes passed to child components, actions modify the DOM directly
      - **Use case**: Transformers are ideal for conditional attribute values that need to be available to child components

      ## Available Transformers

      For a complete list of built-in attribute transformers, see **[Attribute Transformers Reference](../core/attributeTransformer/index)**.

      ## Extensibility

      The Attribute Transformer system is fully extensible through the plugin system. You can create custom transformers to handle specific attribute manipulation needs in your application.

      ### Creating Custom Attribute Transformers

      Attribute transformers are JavaScript functions that receive attributes and transformation properties, then return the modified attributes:

  - type: SyntaxHighlighter
    language: javascript
    content: |
      // customTransformer.js
      export const myCustomTransformer = ({ attributes, globalDataContext, singleTransformProps, templateContext }) => {
          const { name, customProperty } = singleTransformProps;
          
          // Your custom logic here
          // Modify the attributes object
          
          return attributes;
      };

  - type: Markdown
    content: |
      ### Plugin Registration

      Include your custom transformers in a plugin and register them with ReactiveJsonRoot:

  - type: SyntaxHighlighter
    language: javascript
    content: |
      // myPlugin.js
      import { myCustomTransformer } from "./transformers/customTransformer.js";

      export const myPlugin = {
          attributeTransformer: {
              myCustomTransformer,
          }
      };

  - type: SyntaxHighlighter
    language: javascript
    content: |
      // App.js
      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
      import { myPlugin } from "./plugins/myPlugin.js";

      const App = () => {
          return (
              <ReactiveJsonRoot
                  plugins={mergeComponentCollections([myPlugin])}
              />
          );
      };

  - type: Markdown
    content: |
      ### Usage in RjBuild

      Once registered, your custom transformer can be used in any element:

  - type: TabbedSerializer
    yamlSerializedContent: |
      renderView:
        - type: div
          attributes:
            class: "base-class"
          attributeTransforms:
            - what: myCustomTransformer
              name: "data-custom"
              customProperty: "value"
              when: ~~.someCondition
              is: true

  - type: Markdown
    content: |
      For detailed component development guidance, see **[Plugin Development](./plugins/index)**.

      ## Execution Order

      Attribute transformers are applied in the order they appear in the `attributeTransforms` array:

      1. Base attributes are evaluated (template resolution)
      2. Each transformer is applied sequentially
      3. The final attributes are passed to the component/element

      ## Conditional Execution

      All attribute transformers support the same conditional system as actions:

      - **`when`**: Specifies the data value to evaluate
      - **`is`**: Exact value comparison
      - **`isEmpty`/`isNotEmpty`**: Empty/non-empty checks
      - **Template evaluation**: Full support for `~.`, `~~.`, `~>`, `~~>` patterns

data:
  page_title: "Attribute Transformers - Reactive-JSON Documentation"