afv-library/skills/generating-experience-lwr-site/docs/handle-ui-components.md

UI Component Handling

Use when adding/configuring components to be used in Experience site.

Component Insertion

Insert custom Lightning Web Components (LWC) into views.

What is a Custom Component?

Any LWC in c namespace (e.g., c:heroBanner). Distinct from OOTB components (e.g., community_builder:htmlEditor).

Prerequisites for Custom LWC

js-meta.xml Requirements:

• <isExposed>true</isExposed>
• Targets: lightningCommunity__Page, lightningCommunity__Default

Property Type Constraints (MANDATORY GATE):

1. Supported: String, Integer, Boolean, Color, Picklist
2. Unsupported: Any other type → STOP immediately
   • Do NOT delete, comment, or auto-correct
   • Advise user to set up Custom Property Editor (CPE) or Custom Property Type
3. Type Mismatch: type="Number" → change to type="Integer" in js-meta.xml

Do not proceed until LWC files are compliant or user advised on CPE/CPT.

Placement Hierarchy

NEVER place components directly in top-level regions. Must nest inside community_layout:section → column region.

community_layout:sldsFlexibleLayout (root)
└── region (content/header/footer)
    └── community_layout:section
        └── region (column: col1/col2)
            └── component(s)

Column Width & Layout

12-unit grid: Column widths sum to 12 per section.

Width Formats:

• Grid units: 8 + 4
• Percentages: 66% + 33% → 8 + 4; 50% + 50% → 6 + 6
• Ratios: 2:1 → 8 + 4; 1:1 → 6 + 6; equal thirds → 4 + 4 + 4

Layout Rules:

• One section = one horizontal row
• Multiple rows = multiple sections (siblings)
• Multiple components in column = vertical stack

Set width in sectionConfig (JSON string attribute on section component).

sectionConfig Structure

Top-level (when parsed):

• UUID: Section ID (matches section component's id)
• columns: Array of column definitions

Each column:

• UUID: Column ID (matches column region's id)
• columnKey: Column identifier (e.g., col1, col2) - matches column region's name
• columnName: Display name (e.g., "Column 1")
• columnWidth: String from "1" to "12" (must sum to 12)
• seedComponents: Array or null (typically [] or null)

Example (serialized as JSON string in sectionConfig attribute):

{
  "UUID": "295e6a8b-fd94-485b-af9d-7ccf5b3048ee",
  "columns": [
    {
      "UUID": "7e1f7e33-5ba8-4fef-8494-6ea3e90b22a0",
      "columnKey": "col1",
      "columnName": "Column 1",
      "columnWidth": "12",
      "seedComponents": null
    }
  ]
}

Named Region Creation

In order to create a component with drag-n-droppable region/slot that can be used in Experience Builder sites and persist across views, there are multiple steps needed.

Page layout components should add the lightningCommunity__Page_Layout target in js-meta.xml. Theme layout components should add the lightningCommunity__Theme_Layout target in js-meta.xml. Add lightningCommunity__Page as a target for page layouts and any component with slots that is not explicitly defined as a theme layout.

The js file in LWC need to declare named slots:

/**
 * @slot header
 * @slot footer
 */
export default class YourComponentName extends LightningElement {}

Do not add any other comments in the declaration comment block. The named @slot annotations must be the last comments in the block before the class declaration.

In html, named slots are needed. and in the above example.

For theme layout component, a with no name is the main content region, a slot with name is a sticky region that doesn't change from page to page that uses the same theme layout component.

No need to declare target config properties for the slots/regions. See the example below for adding a component with named slots into a view.

Component Structure

{
  "id": "[UNIQUE_UUID]",
  "type": "component",
  "definition": "[NAMESPACE]:[COMPONENT_NAME]",
  "attributes": {
    "[ATTRIBUTE_NAME]": "[ATTRIBUTE_VALUE]"
  }
}

Field Definitions:

• id: Unique UUID (see handle-component-and-region-ids.md)
• type: Always "component"
• definition:
  • Custom LWC: c:[componentName] (e.g., c:heroBanner)
  • OOTB: [namespace]:[componentName] (e.g., community_builder:richTextEditor)
• attributes: Component properties
  • Omit if no attributes (don't include empty object)
  • Custom LWC: Only @api properties in targetConfigs (with lightningCommunity__Default target)
  • OOTB: Only exposed schema properties

Complete Examples

Example 1: Overall structure Correct nesting: content region → section → column region → components

{
  "type": "region",
  "name": "content",
  "children": [
    {
      "attributes": {
        "sectionConfig": "{\"UUID\":\"295e6a8b-fd94-485b-af9d-7ccf5b3048ee\",\"columns\":[{\"UUID\":\"7e1f7e33-5ba8-4fef-8494-6ea3e90b22a0\",\"columnName\":\"Column 1\",\"columnKey\":\"col1\",\"columnWidth\":\"12\",\"seedComponents\":null}]}"
      },
      "children": [
        {
          "children": [
            {
              "definition": "c:testComponent",
              "id": "2ae498bd-2871-487d-8fb1-b186376cee3b",
              "type": "component"
            },
            {
              "id": "7c7d3b6a-1e2f-4a33-9c1e-8b2a6d5f4e3b",
              "type": "component",
              "definition": "c:helloWorld",
              "attributes": {
                "title": "Hello"
              }
            }
          ],
          "id": "7e1f7e33-5ba8-4fef-8494-6ea3e90b22a0",
          "name": "col1",
          "title": "Column 1",
          "type": "region"
        }
      ],
      "definition": "community_layout:section",
      "id": "295e6a8b-fd94-485b-af9d-7ccf5b3048ee",
      "type": "component"
    }
  ]
}

CRITICAL: Follow UUID generation process (handle-component-and-region-ids.md) when inserting components.

Example 2: Representing slots If a component with slots (i.e. @slot annotation) is inserted, slots must appear as named regions. In this example the component threeColumn has 3 slots, named left, center, and right.

{
    "attributes" : { },
    "children" : [ {
    "id" : "4c6148c7-c07e-4245-ae50-ac07891046f2",
    "name" : "left",
    "title" : "left",
    "type" : "region"
    }, {
    "id" : "f362e789-7f09-40b4-a59f-03f76ea73401",
    "name" : "center",
    "title" : "center",
    "type" : "region"
    }, {
    "id" : "2678ddd4-a1a4-41c4-bf5a-1a3e55891eb2",
    "name" : "right",
    "title" : "right",
    "type" : "region"
    } ],
    "definition" : "c:threeColumn",
    "id" : "b9e517c5-90ac-49e9-91b7-3730512c95a3",
    "type" : "component"
}