mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-02 05:09:27 +08:00
30052ef628
* feat: update theme layout creation instructions * fix: revert UI component section * feat: specify order of operations for theme layout creation --------- Co-authored-by: Hemant Singh Bisht <hsinghbisht@salesforce.com>
146 lines
5.1 KiB
Markdown
146 lines
5.1 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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**:
|
|
|
|
```json
|
|
{
|
|
"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](docs/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](docs/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`).
|