afv-library/skills/generating-experience-lwr-site/docs/configure-content-themeLayout.md

Content Type: sfdc_cms__themeLayout

Use when user explicitly requests creating a new layout.

Table of Contents

• Directory Structure

• Purpose A: Generate new theme layouts under the sfdc_cms__themeLayout directory.

  • _meta.json Structure
  • content.json Structure
  • Naming Conventions
  • Theme Sync After Creation
  • Generation Checklist

• Purpose B: Editing existing theme layouts under the sfdc_cms__themeLayout directory.

Directory Structure

1. Location: digitalExperiences/site/[SITE_NAME]/sfdc_cms__themeLayout/[THEME_LAYOUT_NAME]/
2. Required Files:

• _meta.json - Metadata file defining the API name and type
• content.json - Content file defining the configuration and layout

Purpose A: Generate New Theme Layouts

IMPORTANT: These guidelines should ONLY be applied when the user explicitly requests creating a new layout for their site. Do not apply these guidelines automatically for other tasks or when editing existing layouts.

Order of operations

If the user decides to create a new LWC, create the LWC first THEN the theme layout metadata.

_meta.json Structure

The _meta.json file must contain:

{
  "apiName": "[THEME_LAYOUT_NAME]",
  "type": "sfdc_cms__themeLayout",
  "path": "themeLayouts"
}

Rules:

• apiName: Must match the themeLayout directory name exactly
• type: Always "sfdc_cms__themeLayout"
• path: Always "themeLayouts"

content.json Structure

The content.json file must contain:

{
  "type": "sfdc_cms__themeLayout",
  "title": "[DISPLAY_TITLE]",
  "contentBody": {
    "component": {
        "attributes": { },
        "children": [ "[regions in the layout]" ],
        "definition": "[FQN of root layout component]",
        "id": "[root component id]",
        "type": "component"
    }
  },
  "urlName": "[url name]"
}

Field Definitions:

• type: Always "sfdc_cms__themeLayout"
• title: Human-readable display title, words separated by spaces (e.g. "Scoped Header and Footer")
• contentBody: Include all required properties from schemaDefinition. Use examplesOfContentType for reference.
• Do not add additional fields.
• urlName: URL identifier (lowercase, words separated by dashes e.g., "scoped-header-and-footer")
• contentBody.compnent.definition: The actual theme layout component that displays/renders the layout and includes theme region components.

Rules:

• Before any actions, always call execute_metadata_action to get the full schema and examples per the skill document.

Naming Conventions

1. Directory Name: Should be in camelCase
2. apiName: Must exactly match the directory name
3. title: Human-readable title with spaces (e.g., "Service Not Available Theme Layout")
4. urlName: Lowercase with hyphens for URL-friendly format (e.g., "new-layout")

Theme Sync After Creation

After creating a new sfdc_cms__themeLayout, you MUST update:

digitalExperiences/site/[SITE_NAME]/sfdc_cms__theme/[THEME_API_NAME]/content.json

Lookup: To find the theme content.json for the current site:

1. Navigate up from the current theme layout directory to the site directory.
2. Look in sfdc_cms__theme/ (sibling directory to sfdc_cms__themeLayout/).
3. Find the theme directory (typically one per site).
4. Read the file: content.json.

Action (append-only):

• ALWAYS append a new entry to contentBody.layouts.
• Do NOT replace or remove existing layouts entries.
• layoutId MUST exactly match the new theme layout apiName.
• layoutType MUST be chosen based on intended view usage.
  • Default: Generate a random 30-character alphanumeric string (e.g., xEGgPxY5j5TForZe3J7SBguOfQicEy) for the layoutType. Ensure this string is unique and does not match any existing layoutType in the list.

Example:

{
  "contentBody": {
    "layouts": [
      { "layoutId": "existingLayoutA", "layoutType": "Inner" },
      { "layoutId": "existingLayoutB", "layoutType": "ServiceNotAvailable" },
      { "layoutId": "[NEW_THEME_LAYOUT_API_NAME]", "layoutType": "[30_CHAR_RANDOM_STRING]" }
    ]
  }
}

Generation Checklist

When generating a new theme layout, ensure:

• _meta.json created with correct apiName, type, and path
• content.json created with all required fields
• urlName uses lowercase with hyphens
• title is human-readable
• sfdc_cms__theme/[THEME_API_NAME]/content.json updated by appending a new contentBody.layouts mapping
• CRITICAL: Complete all the UUID generation steps. See handle-component-and-region-ids.md

Purpose B: Editing Existing Theme Layouts

Component Modifications

When adding, removing, or configuring components in existing theme layouts, always refer to handle-ui-components.md for placement hierarchy, component structure, column layout, and property configuration.

Note: Theme layouts often define the overall structure (header/footer) surrounding the main content region. Ensure components are added to the correct region (e.g., header, footer).