kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-08-10 09:41:17 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

@W-20113791 Update flexipage skill to reflect best practices

Browse Source
This commit is contained in:
Ethan Clapham 2026-03-13 14:55:05 -07:00
parent 95be7a36fb
commit 2c2ab90576
7 changed files with 637 additions and 246 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

413
skills/salesforce-flexipage/SKILL.md
View File

@ -1,77 +1,31 @@
--- ---
name: salesforce-flexipage name: salesforce-flexipage
description: Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like "create a Lightning page", "add a component to a page", "customize the record page", "generate a FlexiPage", or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention "page" in the context of Salesforce. description: Generate valid, deployable Salesforce Lightning Page (FlexiPage) metadata XML. Always use this skill when working with .flexipage-meta.xml files. Trigger when users mention Lightning pages, creating pages, adding components to pages, or page customization. Always use this skill for any FlexiPage-related work, even if they just mention "page" in the context of Salesforce.
--- ---
# CONTEXT
## When to Use This Skill ## When to Use This Skill
Use this skill when you need to: Use this skill when you need to:
- Create Lightning pages (RecordPage, AppPage, HomePage) - Edit ANY `*.flexipage-meta.xml` file
- Generate FlexiPage metadata XML - Create new Lightning Pages (FlexiPages) for records, apps, or home pages
- Add components to existing FlexiPages - Edit existing pages by adding or changing components
- Troubleshoot FlexiPage deployment errors - Troubleshoot FlexiPage deployment errors
- Understand FlexiPage structure and component configuration
- Work with page layouts or Lightning page customization
- Edit or update ANY *.flexipage-meta.xml file
## Specification ## Goal
# FlexiPage Generation Guide Generate valid, deployable FlexiPage metadata XML using CLI bootstrapping, with incremental enhancement and deployment. Ensure all generated XML follows Salesforce metadata conventions and passes deployment validation.
## Overview ## Overview
Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration. Generate Lightning Pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration.
**Terminology:** Lightning Pages are the marketing/UX name for FlexiPage metadata. Users may refer to them simply as "pages", "Lightning pages", or "FlexiPages". The metadata type is `FlexiPage` and files use the `.flexipage-meta.xml` extension.
--- ---
## Quick Start Workflow # CRITICAL FOUNDATION (Read First!)
### Step 1: Bootstrap with CLI
```bash
sf template generate flexipage \
--name <PageName> \
--template <RecordPage|AppPage|HomePage> \
--sobject <SObject> \
--primary-field <Field1> \
--secondary-fields <Field2,Field3> \
--detail-fields <Field4,Field5,Field6,Field7> \
--output-dir force-app/main/default/flexipages
```
**Template-specific requirements:**
- **RecordPage**: Requires `--sobject` (e.g., Account, Custom_Object__c)
- **RecordPage**: Requires `--primary-field` and `--secondary-fields` for dynamic highlights, `--detail-fields` for full record details. Use the most important identifying field as primary, e.g. Name. Use the secondary fields (max 12, recommended 4-6) to show a summary of the record. Use detail fields to show the full details of the record.
- **AppPage**: No additional requirements
- **HomePage**: No additional requirements
**Note:** If the `sf template generate flexipage` command fails, recommend users upgrade to the latest version of the Salesforce CLI:
```bash
npm install -g @salesforce/cli@latest
```
**What you get:**
- Valid FlexiPage XML with correct structure
- Pre-configured regions and basic components
- Proper field references and facet structure
- Ready to deploy as-is or enhance further
### Step 2: Deploy Base Page
```bash
sf project deploy start --source-dir force-app/main/default/flexipages
```
**Deploy early, deploy often.** Start with the bootstrapped page, validate it works, then enhance.
### Step 3: Update and Redeploy
Modify the generated XML, adding components discovered via MCP. Deploy incrementally.
**Note:** Warn users to use caution with updates beyond this step when using this command.
---
## Critical XML Rules ## Critical XML Rules
@ -101,14 +55,14 @@ Modify the generated XML, adding components discovered via MCP. Deploy increment
### 2. Field References ### 2. Field References
**ALWAYS:** `Record.{FieldApiName}` **ALWAYS:** `Record.{FieldApiName}`
**NEVER:** `{ObjectName}.{FieldApiName}` **NEVER:** `{ObjectName}.{FieldApiName}`
```xml ```xml
<!-- Correct --> <!-- Correct -->
<fieldItem>Record.Name</fieldItem> <fieldItem>Record.Name</fieldItem>
<!-- Wrong --> <!-- Wrong -->
<fieldItem>Account.Name</fieldItem> <fieldItem>Account.Name</fieldItem>
``` ```
@ -130,7 +84,7 @@ Modify the generated XML, adding components discovered via MCP. Deploy increment
### 4. fieldInstance Structure ### 4. fieldInstance Structure
Every fieldInstance requires: Ensure every fieldInstance includes:
```xml ```xml
<itemInstances> <itemInstances>
<fieldInstance> <fieldInstance>
@ -145,83 +99,141 @@ Every fieldInstance requires:
``` ```
**Rules:** **Rules:**
- Each fieldInstance in its own `<itemInstances>` wrapper - Place each fieldInstance in its own `<itemInstances>` wrapper
- Must have `fieldInstanceProperties` with `uiBehavior` - Always include `fieldInstanceProperties` with `uiBehavior`
- Use `Record.{Field}` format - Always use `Record.{Field}` format
--- ---
## Common Deployment Errors ## Component-Specific Rules
### "Invalid field reference" **REQUIRED READING:** Before working with ANY component, you MUST read the relevant documentation files. This is NOT optional.
**Cause:** Used `ObjectName.Field` instead of `Record.Field`
**Fix:** Change to `Record.{FieldApiName}`
### "Element fieldInstance is duplicated" ### Mandatory Documentation by Component Type
**Cause:** Multiple fieldInstances in one itemInstances
**Fix:** Each fieldInstance needs its own `<itemInstances>` wrapper
### "Missing fieldInstanceProperties" **Container Components** (tabs, accordions, field sections):
**Cause:** No uiBehavior specified - **MUST READ:** `examples/container-facets-example.xml`
**Fix:** Add `fieldInstanceProperties` with `uiBehavior` - This shows the correct facet structure that is required for all container components
- Read this BEFORE generating any container component XML
### "Unused Facet" **Related Lists** (`lst:dynamicRelatedList`):
**Cause:** Facet defined but not referenced by any component - **MUST READ:** `docs/components/lst-dynamicRelatedList.md`
**Fix:** Remove Facet or reference it in a component property - Contains critical rules for `parentFieldApiName`, `relatedListApiName`, and field configuration
- Inform the user you've read this file (the file itself requires this)
### "XML parsing error" **Other Component Documentation:**
**Cause:** Unencoded HTML/XML in property values - `record_flexipage-dynamicHighlights.md` - RecordPage header / summary (MUST read when working with highlights)
**Fix:** Manually encode `<`, `>`, `&`, `"`, `'` in all `<value>` tags - `flexipage-fieldSection.md` - Field display columns (MUST read when working with field sections)
- `flexipage-richText.md` - Rich text content (MUST read when working with rich text)
### "Cannot create component with namespace" **General Rule:** For ANY component listed above, you MUST read its documentation file BEFORE generating XML. For components without specific documentation, apply the general Critical XML Rules.
**Cause:** Invalid page name (don't use `__c` suffix in page names)
**Fix:** Use "Volunteer_Record_Page" not "Volunteer__c_Record_Page"
### "Region specifies mode that parent doesn't support"
**Cause:** Added `<mode>` tag to region
**Fix:** Remove `<mode>` tags - they're not needed for standard regions
--- ---
## Incremental Development Pattern ## Component Selection Guidelines
**Philosophy:** Deploy small, working increments. Don't build entire complex page at once. When choosing components, prefer the following options for better performance and flexibility:
**Process:** 1. **Related Lists:** ALWAYS use `lst:dynamicRelatedList` for related lists. Do NOT use `force:relatedListQuickLink` or `force:relatedListSingleContainer`. The `lst:dynamicRelatedList` component is more performant and offers more FlexiPage configuration options. When using this component, you MUST read `docs/components/lst-dynamicRelatedList.md` before proceeding.
1. **CLI bootstrap** → Deploy base page
2. **Add one component** → Deploy
3. **Add another component** → Deploy
4. **Repeat** until complete
**Benefits:** 2. **Field Display:** Prefer field sections with specific fields over `force:detailPanel`. Field sections provide more versatility and control over layout and field behavior.
- Isolated errors (know exactly what broke)
- Faster debugging
- Build confidence with each success
- Get user feedback early
**Anti-pattern:** Building entire complex page → one giant error cascade.
--- ---
## Adding Components to Existing FlexiPages # MAIN WORKFLOWS
### Workflow ## Decision Tree: New Page or Existing Page?
When user provides an existing FlexiPage file path: **Does the FlexiPage file already exist?**
1. **Read the file** using native file I/O - **NO** → Use "Creating New Pages" workflow below (bootstrap first, then add components)
- **YES** → Skip to "Adding/Editing Components" workflow (no bootstrap needed)
---
## Creating New Pages
**Use this workflow when the `.flexipage-meta.xml` file does NOT exist yet.**
### Step 1: Bootstrap with CLI
```bash
sf template generate flexipage \
--name <PageName> \
--template <RecordPage|AppPage|HomePage> \
--sobject <SObject> \
--primary-field <Field1> \
--secondary-fields <Field2,Field3> \
--detail-fields <Field4,Field5,Field6,Field7> \
--output-dir force-app/main/default/flexipages
```
**Template-specific requirements:**
- **RecordPage**: Requires `--sobject` (e.g., Account, Custom_Object__c)
- **RecordPage**: Requires `--primary-field` and `--secondary-fields` for dynamic highlights, `--detail-fields` for full record details. Use the most important identifying field as primary, e.g. Name. Use the secondary fields (max 12, recommended 4-6) to show a summary of the record. Use detail fields to show the full details of the record.
- **AppPage**: No additional requirements
- **HomePage**: No additional requirements
**Note:** If the `sf template generate flexipage` command fails, recommend users upgrade to the latest version of the Salesforce CLI:
```bash
npm install -g @salesforce/cli@latest
```
**What you get:**
- Valid FlexiPage XML with correct structure
- Pre-configured regions and basic components
- Proper field references and facet structure
- Ready to deploy as-is or enhance further
### Step 2: Deploy Base Page
```bash
sf project deploy start --source-dir force-app/main/default/flexipages
```
**Deploy early, deploy often.** Start with the bootstrapped page, validate it works, then enhance.
### Step 3: Add More Components (if needed)
If the user wants to add additional components beyond what the CLI generated, proceed to the "Adding/Editing Components" workflow below. The process is identical whether you just bootstrapped a new page or are working with an existing page.
---
## Adding/Editing Components
**Use this workflow when:**
- The FlexiPage file already exists, OR
- You've just bootstrapped a new page and need to add more components
### Workflow Steps
1. **Read the FlexiPage file** using native file I/O
2. **Parse XML** to extract: 2. **Parse XML** to extract:
- Existing component identifiers - Existing component identifiers
- Available regions (parse from file, don't assume names) - Available regions (parse from file, don't assume names)
- Existing facets - Existing facets
3. **Generate component XML** (apply all rules from "Critical XML Rules" section) 3. **Select component** based on the user's request
4. **Insert** into appropriate region 4. **READ REQUIRED DOCUMENTATION** - See "Component-Specific Rules" section and read ALL relevant documentation files for your component type (this is MANDATORY, not optional)
5. **Write** modified XML back to file 5. **Generate component XML** using only known, valid properties (apply all rules from "Critical XML Rules" section AND component-specific documentation)
6. **Deploy**: `sf project deploy start --source-dir force-app/...` 6. **Insert** into appropriate region
7. **Write** modified XML back to file
8. **Deploy**: `sf project deploy start --source-dir force-app/...`
--- ---
### Generating Unique Identifiers # IMPLEMENTATION DETAILS
## Container Components with Facets
When generating tabs, accordions, or field sections, always create corresponding facet regions. Components like these require facets to define content areas.
**Critical**: Facet regions are siblings of template regions at the same level, not nested inside them.
**MANDATORY**: Before generating ANY container component, you MUST read [examples/container-facets-example.xml](examples/container-facets-example.xml). This file shows the exact structure required for container components with facets. Reading this file is NOT optional.
---
## Generating Unique Identifiers
**Algorithm**: **Algorithm**:
``` ```
@ -255,14 +267,14 @@ When user provides an existing FlexiPage file path:
--- ---
### Region Selection ## Region Selection
**Parse regions from file** - don't hardcode names. Templates vary: Always parse regions from the file - never hardcode region names. Templates vary:
- `flexipage:recordHomeTemplateDesktop` → `header`, `main`, `sidebar` - `flexipage:recordHomeTemplateDesktop` → `header`, `main`, `sidebar`
- `runtime_service_fieldservice:...` → `header`, `main`, `footer` - `runtime_service_fieldservice:...` → `header`, `main`, `footer`
- Others may have different region names - Others may have different region names
**Default placement**: End of target region (after last `<itemInstances>`) Place new components at the end of the target region (after last `<itemInstances>`)
**Insertion pattern**: **Insertion pattern**:
```xml ```xml
@ -279,101 +291,53 @@ When user provides an existing FlexiPage file path:
--- ---
### Container Components with Facets # QUALITY & DEPLOYMENT
Components like tabs, accordions, field sections require facets. ## Incremental Development Pattern
**Pattern**: **Philosophy:** Deploy small, working increments. Don't build entire complex page at once.
```xml
<!-- 1. Component in region -->
<flexiPageRegions>
<itemInstances>
<componentInstance>
<componentName>flexipage:tabset2</componentName>
<identifier>tabs_main_1</identifier>
<componentInstanceProperties>
<name>tabs</name>
<value>tab1_content</value>
<value>tab2_content</value>
</componentInstanceProperties>
</componentInstance>
</itemInstances>
<name>main</name>
<type>Region</type>
</flexiPageRegions>
<!-- 2. Facets (siblings of region, NOT nested inside) --> **Process:**
<flexiPageRegions> 1. **For new pages: CLI bootstrap** → Deploy base page
<itemInstances><!-- Tab 1 content --></itemInstances> 2. **Add one component** → Deploy
<name>tab1_content</name> 3. **Add another component** → Deploy
<type>Facet</type> 4. **Repeat** until complete
</flexiPageRegions>
<flexiPageRegions> **Benefits:**
<itemInstances><!-- Tab 2 content --></itemInstances> - Isolated errors (know exactly what broke)
<name>tab2_content</name> - Faster debugging
<type>Facet</type> - Build confidence with each success
</flexiPageRegions> - Get user feedback early
```
**Critical**: Facet regions are siblings of template regions at the same level, not nested inside them. **Anti-pattern:** Building entire complex page → one giant error cascade.
---
## Component-Specific Tips
### dynamicHighlights (RecordPage Header)
**Location:** Must be in `header` region.
**Explicit Fields** (via CLI): Use the most important fields to show a summary of the record. The single primary field is used to identify the record, like a name. The secondary fields (max 12, recommended 6) are used as a summary of the record.
```bash
--primary-field Name
--secondary-fields Phone,Industry,AnnualRevenue
```
CLI generates Facets with field references automatically.
### fieldSection
**Use for:** Displaying fields in columns.
**Structure:** Three-level nesting:
1. Template Region (Region type)
2. Column Facets (Facet type)
3. Field Facets (Facet type)
**Referenced in component property:**
```xml
<componentInstanceProperties>
<name>columns</name>
<value>Facet-{uuid}</value>
</componentInstanceProperties>
```
### rich Text component
Component name: flexipage:richText
Use for: Displaying HTML-formatted rich text content with support for text formatting, headings, lists, tables, images, links, forms, and multimedia elements. Preserves styling and layout. Escape all special characters in the default text.
Location: Can be used in any region on any page type (Home, Record, App, Community pages).
CLI generates the component directly without nested structures.
User: "Add a rich text component to force-app/.../Account_Record_Page.flexipage-meta.xml"
Structure: Single-level component (no facets):
1. Component instance (flexipage:richText) with direct properties
XML Structure Example:
```xml
<itemInstances>
<componentInstance>
<componentInstanceProperties>
<name>decorate</name>
<value>true</value>
</componentInstanceProperties>
<componentName>flexipage:richText</componentName>
<identifier>flexipage_richText</identifier>
</componentInstance>
</itemInstances>
```
Identifier Pattern: flexipage_richText or flexipage_richText_{sequence}
--- ---
## Validation Checklist
Before deploying:
- [ ] If creating new page: Used CLI to bootstrap (don't start from scratch)
- [ ] All field references use `Record.{Field}` format
- [ ] Each fieldInstance has `fieldInstanceProperties` with `uiBehavior`
- [ ] Each fieldInstance in own `<itemInstances>` wrapper
- [ ] Template regions use `<type>Region</type>`
- [ ] Component facets use `<type>Facet</type>`
- [ ] Component-specific docs have been read for each component and all rules followed
- [ ] Property values with HTML/XML are manually encoded
- [ ] No `<mode>` tags in regions
- [ ] No `__c` suffix in page names
- [ ] Each Facet referenced by exactly one component property
---
## Common Deployment Errors
See [docs/common-deployment-errors.md](docs/common-deployment-errors.md) for detailed error patterns, causes, and fixes.
---
# REFERENCE
## Required Metadata Structure ## Required Metadata Structure
```xml ```xml
@ -397,49 +361,6 @@ Identifier Pattern: flexipage_richText or flexipage_richText_{sequence}
--- ---
## Validation Checklist ## Output
Before deploying: A valid `.flexipage-meta.xml` file containing properly structured FlexiPage XML with correct region types, field references, component identifiers, and encoded property values
- [ ] Used CLI to bootstrap (don't start from scratch)
- [ ] All field references use `Record.{Field}` format
- [ ] Each fieldInstance has `fieldInstanceProperties` with `uiBehavior`
- [ ] Each fieldInstance in own `<itemInstances>` wrapper
- [ ] Template regions use `<type>Region</type>`
- [ ] Component facets use `<type>Facet</type>`
- [ ] Property values with HTML/XML are manually encoded
- [ ] No `<mode>` tags in regions
- [ ] No `__c` suffix in page names
- [ ] Each Facet referenced by exactly one component property
---
## Quick Reference: CLI Command
```bash
# RecordPage with fields
sf template generate flexipage \
--name Account_Custom_Page \
--template RecordPage \
--sobject Account \
--primary-field Name \
--secondary-fields Phone,Industry,AnnualRevenue \
--detail-fields Street,City,State,Name,Phone,Email
# AppPage
sf template generate flexipage \
--name Sales_Dashboard \
--template AppPage \
--label "Sales Dashboard"
# HomePage
sf template generate flexipage \
--name Custom_Home \
--template HomePage \
--description "Custom home for sales team"
```
**All templates support:**
- `--output-dir` (default: current directory)
- `--api-version` (default: latest)
- `--label` (default: page name)
- `--description`

138
skills/salesforce-flexipage/docs/common-deployment-errors.md Normal file
View File

@ -0,0 +1,138 @@
# Common FlexiPage Deployment Errors
## "Invalid field reference"
**Cause:** Used `ObjectName.Field` instead of `Record.Field`
**Fix:** Change to `Record.{FieldApiName}`
**Example:**
```xml
<!-- Wrong -->
<fieldItem>Account.Name</fieldItem>
<!-- Correct -->
<fieldItem>Record.Name</fieldItem>
```
## "Element fieldInstance is duplicated"
**Cause:** Multiple fieldInstances in one itemInstances wrapper
**Fix:** Each fieldInstance needs its own `<itemInstances>` wrapper
**Example:**
```xml
<!-- Wrong -->
<itemInstances>
<fieldInstance>
<fieldItem>Record.Name</fieldItem>
</fieldInstance>
<fieldInstance>
<fieldItem>Record.Phone</fieldItem>
</fieldInstance>
</itemInstances>
<!-- Correct -->
<itemInstances>
<fieldInstance>
<fieldItem>Record.Name</fieldItem>
</fieldInstance>
</itemInstances>
<itemInstances>
<fieldInstance>
<fieldItem>Record.Phone</fieldItem>
</fieldInstance>
</itemInstances>
```
## "Missing fieldInstanceProperties"
**Cause:** No uiBehavior specified
**Fix:** Add `fieldInstanceProperties` with `uiBehavior`
**Example:**
```xml
<!-- Wrong -->
<fieldInstance>
<fieldItem>Record.Name</fieldItem>
<identifier>RecordNameField</identifier>
</fieldInstance>
<!-- Correct -->
<fieldInstance>
<fieldInstanceProperties>
<name>uiBehavior</name>
<value>none</value>
</fieldInstanceProperties>
<fieldItem>Record.Name</fieldItem>
<identifier>RecordNameField</identifier>
</fieldInstance>
```
## "Unused Facet"
**Cause:** Facet defined but not referenced by any component
**Fix:** Remove Facet or reference it in a component property
**Example:**
```xml
<!-- Component must reference the facet -->
<componentInstanceProperties>
<name>body</name>
<value>detailTabContent</value>
</componentInstanceProperties>
<!-- And the facet must exist -->
<flexiPageRegions>
<name>detailTabContent</name>
<type>Facet</type>
</flexiPageRegions>
```
## "XML parsing error"
**Cause:** Unencoded HTML/XML in property values
**Fix:** Manually encode `<`, `>`, `&`, `"`, `'` in all `<value>` tags
**Encoding order (important!):**
1. `&` → `&amp;` (FIRST! Encode this before others)
2. `<` → `&lt;`
3. `>` → `&gt;`
4. `"` → `&quot;`
5. `'` → `&apos;`
**Example:**
```xml
<!-- Wrong -->
<value><b>Important</b> text & notes</value>
<!-- Correct -->
<value>&lt;b&gt;Important&lt;/b&gt; text &amp; notes</value>
```
## "Cannot create component with namespace"
**Cause:** Invalid page name (don't use `__c` suffix in page names)
**Fix:** Use "Volunteer_Record_Page" not "Volunteer__c_Record_Page"
**Example:**
```bash
# Wrong
sf template generate flexipage --name Volunteer__c_Record_Page
# Correct
sf template generate flexipage --name Volunteer_Record_Page
```
## "Region specifies mode that parent doesn't support"
**Cause:** Added `<mode>` tag to region
**Fix:** Remove `<mode>` tags - they're not needed for standard regions
**Example:**
```xml
<!-- Wrong -->
<flexiPageRegions>
<name>header</name>
<type>Region</type>
<mode>Replace</mode>
</flexiPageRegions>
<!-- Correct -->
<flexiPageRegions>
<name>header</name>
<type>Region</type>
</flexiPageRegions>
```

16
skills/salesforce-flexipage/docs/components/flexipage-fieldSection.md Normal file
View File

@ -0,0 +1,16 @@
# fieldSection
**Use for:** Displaying fields in columns.
**Structure:** Three-level nesting:
1. Template Region (Region type)
2. Column Facets (Facet type)
3. Field Facets (Facet type)
**Referenced in component property:**
```xml
<componentInstanceProperties>
<name>columns</name>
<value>Facet-{uuid}</value>
</componentInstanceProperties>
```

26
skills/salesforce-flexipage/docs/components/flexipage-richText.md Normal file
View File

@ -0,0 +1,26 @@
# Rich Text Component
**Component name:** `flexipage:richText`
**Use for:** Displaying HTML-formatted rich text content with support for text formatting, headings, lists, tables, images, links, forms, and multimedia elements. Preserves styling and layout. Escape all special characters in the default text.
**Location:** Can be used in any region on any page type (Home, Record, App, Community pages).
**Structure:** Single-level component (no facets):
1. Component instance (flexipage:richText) with direct properties
**XML Structure Example:**
```xml
<itemInstances>
<componentInstance>
<componentInstanceProperties>
<name>decorate</name>
<value>true</value>
</componentInstanceProperties>
<componentName>flexipage:richText</componentName>
<identifier>flexipage_richText</identifier>
</componentInstance>
</itemInstances>
```
**Identifier Pattern:** `flexipage_richText` or `flexipage_richText_{sequence}`

235
skills/salesforce-flexipage/docs/components/lst-dynamicRelatedList.md Normal file
View File

@ -0,0 +1,235 @@
# Quick Example: Adding Related List
User request: Add MyCustomObject related list to the flexipage Parent_Record_Page.flexipage-meta.xml
Steps:
1. Read the flexipage file and parse the XML.
2. Generate unique identifier: `lst_dynamicRelatedList_<childEntityName>_1`
3. Generate component XML with substitution points:
```xml
<itemInstances>
<componentInstance>
<componentName>lst:dynamicRelatedList</componentName>
<!-- SUBSTITUTION POINT: identifier -->
<!-- PATTERN: lst_dynamicRelatedList_<childEntityName>_<number> -->
<!-- MUST BE UNIQUE within the flexipage -->
<identifier>lst_dynamicRelatedList_childEntity_1</identifier>
<componentInstanceProperties>
<name>actionNames</name>
<valueList>
<valueListItems>
<value>New</value>
</valueListItems>
</valueList>
</componentInstanceProperties>
<componentInstanceProperties>
<name>adminFilters</name>
</componentInstanceProperties>
<componentInstanceProperties>
<name>maxRecordsToDisplay</name>
<value>10</value>
</componentInstanceProperties>
<!-- SUBSTITUTION POINT: parentFieldApiName -->
<!-- PATTERN: <ParentEntityApiName>.Id -->
<!-- FOR CUSTOM PARENT: ParentObject__c.Id -->
<!-- ALWAYS ENDS WITH: .Id -->
<componentInstanceProperties>
<name>parentFieldApiName</name>
<value>Parent.Id</value>
</componentInstanceProperties>
<!-- SUBSTITUTION POINT: relatedListApiName -->
<!-- FOR CUSTOM OBJECTS: Use relationshipLabel from lookup field -->
<!-- ALWAYS ENDS WITH: __r for custom objects -->
<!-- EXAMPLE: MyCustomObjects__r -->
<componentInstanceProperties>
<name>relatedListApiName</name>
<value>MyCustomObjects__r</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>relatedListDisplayType</name>
<value>ADVGRID</value>
</componentInstanceProperties>
<!-- SUBSTITUTION POINT: relatedListFieldAliases -->
<!-- FOR CUSTOM OBJECTS: Field API names ending in __c -->
<componentInstanceProperties>
<name>relatedListFieldAliases</name>
<valueList>
<valueListItems>
<value>NAME</value>
</valueListItems>
<valueListItems>
<value>FieldNameOne__c</value>
</valueListItems>
<valueListItems>
<value>FieldNameTwo__c</value>
</valueListItems>
<valueListItems>
<value>FieldNameThree__c</value>
</valueListItems>
</valueList>
</componentInstanceProperties>
<!-- SUBSTITUTION POINT: relatedListLabel -->
<!-- PATTERN: Any display string, typically plural child entity name -->
<componentInstanceProperties>
<name>relatedListLabel</name>
<value>My Custom Objects</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>showActionBar</name>
<value>true</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>sortFieldAlias</name>
<value>__DEFAULT__</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>sortFieldOrder</name>
<value>Default</value>
</componentInstanceProperties>
</componentInstance>
</itemInstances>
```
4. Insert into flexipage at end of "main" region. Append this after the last "itemInstances" element in that region.
5. Write file
It is now ready to deploy.
### Critical Rules for Success
**RULE 1: parentFieldApiName**
- Pattern: `<ParentEntityApiName>.Id`
- Example: Account__c.Id or Customer__c.Id
- ALWAYS ends with ".Id"
- The __c is part of the entity name
**RULE 2: relatedListApiName**
- Source: Use relationshipLabel from the lookup field in child entity
- Pattern: ALWAYS ends with "__r"
- Example: If child is "Subscription__c" → likely "Subscriptions__r"
- This is the child relationship name for parent-to-child traversal
- Typically the plural form of child entity + "__r"
**RULE 3: relatedListFieldAliases**
- For custom objects: Use field API names from child entity
- Pattern: Custom fields ALWAYS end with "__c"
- Examine the child entity metadata and find up to three fields that are not NAME fields. Use the "NAME" field followed by those fields.
**EXAMPLE: multi column list**
```xml
<valueList>
<valueListItems>
<value>NAME</value>
</valueListItems>
<valueListItems>
<value>FieldNameOne__c</value>
</valueListItems>
<valueListItems>
<value>FieldNameTwo__c</value>
</valueListItems>
<valueListItems>
<value>FieldNameThree__c</value>
</valueListItems>
</valueList>
```
**RULE 4: relatedListLabel**
- Can be any user-friendly string
- Commonly: Plural form of child entity name without __c
- Example: "Subscriptions" or "Custom Orders"
- No strict pattern - use descriptive text
**INSERTION RULES**
- This component must be inside its own "itemInstances" element
- The component must go into the "main" region
- Insert the new "itemInstances" element after the last existing "itemInstances" element in that region
**Common Mistakes to Avoid:**
- ❌ Nesting the "itemInstances" element inside another existing "itemInstances" element
- ❌ Inserting a second "componentInstance" element inside an existing "itemInstances" element
- ❌ Using field labels instead of API names
- ❌ Forgetting __c suffix on custom fields
- ❌ Including the lookup field that defines the relationship
- ❌ Including more than 10 fields
### Complete Custom Object Example
**Scenario:** Add "Subscription__c" related list to "Customer__c" record page
**Given:**
- Parent entity: Customer__c
- Child entity: Subscription__c
- Lookup field in Subscription__c: Customer__c (references Customer__c)
- Lookup field's relationshipLabel: "Subscriptions"
- Child fields: Name, Status__c, Start_Date__c, Amount__c
**Generated Component:**
```xml
<itemInstances>
<componentInstance>
<componentName>lst:dynamicRelatedList</componentName>
<identifier>lst_dynamicRelatedList_subscriptions_1</identifier>
<componentInstanceProperties>
<name>actionNames</name>
<valueList>
<valueListItems><value>New</value></valueListItems>
</valueList>
</componentInstanceProperties>
<componentInstanceProperties>
<name>adminFilters</name>
</componentInstanceProperties>
<componentInstanceProperties>
<name>maxRecordsToDisplay</name>
<value>10</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>parentFieldApiName</name>
<value>Customer__c.Id</value> <!-- Parent entity + .Id -->
</componentInstanceProperties>
<componentInstanceProperties>
<name>relatedListApiName</name>
<value>Subscriptions__r</value> <!-- relationshipLabel + __r -->
</componentInstanceProperties>
<componentInstanceProperties>
<name>relatedListDisplayType</name>
<value>ADVGRID</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>relatedListFieldAliases</name>
<valueList>
<valueListItems><value>NAME</value></valueListItems>
<valueListItems><value>Status__c</value></valueListItems>
<valueListItems><value>Start_Date__c</value></valueListItems>
<valueListItems><value>Amount__c</value></valueListItems>
</valueList>
</componentInstanceProperties>
<componentInstanceProperties>
<name>relatedListLabel</name>
<value>Subscriptions</value> <!-- User-friendly display name -->
</componentInstanceProperties>
<componentInstanceProperties>
<name>showActionBar</name>
<value>true</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>sortFieldAlias</name>
<value>__DEFAULT__</value>
</componentInstanceProperties>
<componentInstanceProperties>
<name>sortFieldOrder</name>
<value>Default</value>
</componentInstanceProperties>
</componentInstance>
</itemInstances>
```

12
skills/salesforce-flexipage/docs/components/record_flexipage-dynamicHighlights.md Normal file
View File

@ -0,0 +1,12 @@
# dynamicHighlights (RecordPage Header)
**Location:** Must be in `header` region.
**Explicit Fields** (via CLI): Use the most important fields to show a summary of the record. The single primary field is used to identify the record, like a name. The secondary fields (max 12, recommended 6) are used as a summary of the record.
```bash
--primary-field Name
--secondary-fields Phone,Industry,AnnualRevenue
```
CLI generates Facets with field references automatically.

43
skills/salesforce-flexipage/examples/container-facets-example.xml Normal file
View File

@ -0,0 +1,43 @@
<!-- Example: Tabs Component with Facets -->
<!-- 1. Component in region -->
<flexiPageRegions>
<itemInstances>
<componentInstance>
<componentName>flexipage:tabset2</componentName>
<identifier>tabs_main_1</identifier>
<componentInstanceProperties>
<name>tabs</name>
<value>tab1_content</value>
<value>tab2_content</value>
</componentInstanceProperties>
</componentInstance>
</itemInstances>
<name>main</name>
<type>Region</type>
</flexiPageRegions>
<!-- 2. Facets (siblings of region, NOT nested inside) -->
<flexiPageRegions>
<itemInstances>
<!-- Tab 1 content components go here -->
<componentInstance>
<componentName>force:detailPanel</componentName>
<identifier>force_detailPanel</identifier>
</componentInstance>
</itemInstances>
<name>tab1_content</name>
<type>Facet</type>
</flexiPageRegions>
<flexiPageRegions>
<itemInstances>
<!-- Tab 2 content components go here -->
<componentInstance>
<componentName>runtime_sales_social:socialPanel</componentName>
<identifier>runtime_sales_social_socialPanel</identifier>
</componentInstance>
</itemInstances>
<name>tab2_content</name>
<type>Facet</type>
</flexiPageRegions>