# Core Concepts
Learn the core concepts you need to configure AX App Builder Components effectively in Lightning App Builder.
## **What You'll Learn**
* **Dynamic Data References** – Use field values from the current record, user, or role with {{Record.FieldName}}, {{User.FieldName}}, and {{UserRole.FieldName}} syntax
* **Lightning Page Context** – Understand which page types support which components and how record context works
* **SOQL-Style Configuration** – Write filters, specify fields, and sort data using Salesforce query syntax
* **Salesforce Relationships** – Pull data from parent objects, related records, and custom relationships
**Additional Resources:**
* [**Component Properties Reference**](/app-builder-components/getting-started/understanding-the-essentials/component-properties-reference.md) - Quick lookup for common property patterns
* [**Common Use Case Patterns**](/app-builder-components/getting-started/understanding-the-essentials/common-use-case-patterns.md) - Copy-and-paste solutions for typical scenarios
* [**Troubleshooting & FAQs**](/app-builder-components/resources/troubleshooting-and-faqs.md) - Solutions to common problems
***
## Understanding Dynamic Data References
AX App Builder Components can pull data directly from Salesforce records, users, and roles using dynamic field references in Lightning App Builder. Instead of hard-coding values, your components automatically display information based on the current page context—so the same component configuration works across all records.
### Three Types of Dynamic References
**{{Record.FieldName}}** - Pull data from the current record being viewed **{{User.FieldName}}** - Access information about the logged-in user **{{UserRole.FieldName}}** - Reference the current user's role details
**Need the complete field lists?** Jump to the Appendix: Complete Field References for all available fields.
### The {{Record.FieldName}} Syntax
This is the most commonly used dynamic reference. When configuring Avonni App Builder Components on Lightning Record Pages, use this syntax to insert values from the current record:
```
{{Record.FieldApiName}}
```
Replace `FieldApiName` with the exact API name of any field on the current object.
**Common Use Cases:**
* `{{Record.Id}}` - The record's unique identifier
* `{{Record.Name}}` - The record's name
* `{{Record.OwnerId}}` - The record owner's ID
* `{{Record.Account.Name}}` - Related account name (via lookup)
* `{{Record.Project__r.Manager__c}}` - Custom lookup field value
**Accessing Related Fields:** Use dot notation to traverse lookup relationships:
```
{{Record.LookupField__r.FieldName}}
```
### The {{User.FieldName}} Syntax
Reference information about the current logged-in user to personalize Avonni App Builder Components:
```
{{User.FieldApiName}}
```
**Commonly Used User Fields:**
* `{{User.FirstName}}` and `{{User.LastName}}` - User's name
* `{{User.Email}}` - User's email address
* `{{User.Department}}` - User's department
* `{{User.ManagerId}}` - User's manager
* `{{User.ProfileId}}` - User's profile
{% hint style="success" %}
[See the complete list of available User fields](#user-fields-reference)
{% endhint %}
### The {{UserRole.FieldName}} Syntax
Reference the current user's role information:
```
{{UserRole.FieldApiName}}
```
**Commonly Used UserRole Fields:**
* `{{UserRole.Name}}` - Role name
* `{{UserRole.DeveloperName}}` - Role API name
{% hint style="success" %}
[See the complete list of available UserRole fields](#userrole-fields-reference)
{% endhint %}
***
## Lightning Page Types and Component Context
Understanding where Avonni App Builder Components work and how context affects them is critical for successful implementation.
### Three Lightning Page Types
**Record Pages**
* Display details about a specific record (Account, Opportunity, Case, etc.)
* Have a "current record" context
* **Dynamic references work here:** `{{Record.FieldName}}` pulls from the displayed record
* **Best for:** Related lists, record-specific metrics, contextual information
**App Pages**
* Custom pages within your Salesforce app
* No specific record context
* **Dynamic references don't work:** No "current record" to reference
* **Best for:** Dashboards, reports, data exploration tools
**Home Pages**
* The landing page users see when entering Salesforce
* No specific record context
* **Dynamic references don't work:** No "current record" to reference
* **Best for:** Personal dashboards, company announcements, quick actions
### Why Context Matters
**This Works on Record Pages:**
```
Filter: AccountId = '{{Record.Id}}'
Header Title: Opportunities for {{Record.Name}}
```
**This Does NOT Work on App/Home Pages:**
```
Filter: AccountId = '{{Record.Id}}' ❌ No current record
```
**For App/Home Pages, Use Static or User-Based Filters:**
```
Filter: OwnerId = '{{User.Id}}' ✅ Works everywhere
Header Title: {{User.FirstName}}'s Dashboard ✅ Works everywhere
```
***
## Practical Examples: See It In Action
### Example 1: Show Related Opportunities on an Account Page
**Page Type:** Record Page (Account)
**Filter Configuration:**
```
AccountId = '{{Record.Id}}'
```
**What This Does:**
* When viewing Acme Corp's Account page → shows only Acme Corp's Opportunities
* When viewing Global Industries' Account page → shows only Global Industries' Opportunities
**Important:** Notice the single quotes around `{{Record.Id}}`. This follows SOQL syntax rules where ID and text values must be enclosed in quotes.
**See More Examples:** Check out Common Use Case Patterns for additional real-world scenarios.
### Example 2: Personalized Dashboard on Home Page
**Page Type:** Home Page
**Filter Configuration:**
```
OwnerId = '{{User.Id}}' AND Status = 'Open'
```
**Header Title Configuration:**
```
{{User.FirstName}}'s Open Items
```
**What This Does:** Each user automatically sees only their own open records.
### Example 3: Manager's Team View on App Page
**Page Type:** App Page
**Filter Configuration:**
```
ManagerId = '{{User.Id}}'
```
**What This Does:** Shows only records where the current user is the manager, creating automatic team views.
### Example 4: Related Account Information on Opportunity Page
**Page Type:** Record Page (Opportunity)
**Header Caption Configuration:**
```
Account: {{Record.Account.Name}} | Stage: {{Record.StageName}}
```
**What This Does:** Displays related account name and current stage dynamically.
***
## Working with SOQL-Style Configurations
Now that you understand how to reference data dynamically, let's explore how to filter and structure that data. Avonni App Builder Components use patterns similar to SOQL queries, making configuration familiar to Salesforce administrators.
**For detailed property syntax:** See the Component Properties Reference page.
### Filtering Data
The `filter` property works like a SOQL WHERE clause:
**Simple Filters:**
```
Status = 'Active'
```
**Multiple Conditions:**
```
Priority__c = 'High' AND OwnerId = '{{Record.OwnerId}}'
```
**Date Filters:**
```
CreatedDate = LAST_N_DAYS:30
CloseDate = THIS_MONTH
LastModifiedDate = THIS_YEAR
```
**Excluding Records:**
```
StageName != 'Closed Won' AND StageName != 'Closed Lost'
```
**NULL Checks:**
```
Amount != null
Description = null
```
**Having trouble with filters?** Check the Troubleshooting & FAQs page for common filter issues and solutions.
### Specifying Fields
Use comma-separated field API names (like a SOQL SELECT clause):
```
Name,Email,Phone,Title
```
This tells the component to display these four fields as columns in your table.
**Field Order Matters:** Fields appear in the order you list them.
### Sorting Data
The `orderBy` property works like SOQL's ORDER BY clause:
* `Name` - Ascending by default
* `CreatedDate DESC` - Descending order
* `Priority__c, Name` - Multiple fields (priority first, then name)
***
## Understanding Salesforce Relationships
Avonni App Builder Components become powerful when you leverage Salesforce's relationship structure to show connected data.
**For pre-built relationship patterns:** Visit Common Use Case Patterns for copy-and-paste examples.
### Parent-to-Child Relationships
Show child records from a parent record page.
**Example: Opportunities on Account Page**
```
Object API Name: Opportunity
Filter: AccountId = '{{Record.Id}}'
```
**Example: Cases on Account Page**
```
Object API Name: Case
Filter: AccountId = '{{Record.Id}}'
```
**Example: Contacts on Account Page**
```
Object API Name: Contact
Filter: AccountId = '{{Record.Id}}'
```
### Child-to-Parent Relationships
Reference parent record data from a child record page.
**Example: Account Name on Opportunity Page**
```
Header Caption: {{Record.Account.Name}}
```
**Example: Account Owner on Contact Page**
```
Filter: Account.OwnerId = '{{User.Id}}'
```
### Custom Relationships
Work with custom lookup fields using the `__r` suffix.
**Example: Project Manager from Custom Lookup**
```
Header Caption: Manager: {{Record.Project__r.Manager__c}}
```
**Example: Related Custom Object Records**
```
Object API Name: Custom_Task__c
Filter: Project__c = '{{Record.Id}}'
```
### Junction Objects (Many-to-Many)
Handle many-to-many relationships through junction objects.
**Example: Campaign Members**
```
Object API Name: CampaignMember
Filter: CampaignId = '{{Record.Id}}'
```
**Example: Opportunity Contact Roles**
```
Object API Name: OpportunityContactRole
Filter: OpportunityId = '{{Record.Id}}'
```
***
## Security and Permissions Model
Avonni App Builder Components integrate seamlessly with Salesforce's security framework. Understanding how security works helps you configure components correctly and troubleshoot access issues.
**Experiencing permission issues?** Check the Troubleshooting & FAQs page for security-related solutions.
### Field-Level Security (FLS)
**How It Works:** Avonni App Builder Components automatically respect field-level security settings. If a user doesn't have permission to view a field in Salesforce, they won't see it in the component.
**What This Means:**
* A component configured to show `Amount,CloseDate,Probability` will only display fields the user can access
* Users with limited FLS may see fewer columns than administrators
* No error messages appear; restricted fields simply don't render
**Best Practice:** Test components with users from different profiles to ensure they see appropriate data.
### Object Permissions
**How It Works:** Users must have Read access to the object to see any records in an Avonni App Builder Component.
**Common Issues:**
* Component shows no data even with correct filters → Check object-level Read permission
* Some users see the component, others don't → Profile or permission set differences
### Sharing Rules and Record Access
**How It Works:** Avonni App Builder Components honor all Salesforce sharing rules, including:
* Organization-Wide Defaults (OWD)
* Role hierarchy access
* Sharing rules
* Manual sharing
* Team access
**What This Means:**
* Two users viewing the same Lightning page may see different records
* Filters apply AFTER sharing rules (users only see records they can access)
* Record counts may differ between users
**Example:**
```
Filter: Status = 'Open'
```
This filter shows all Open records the user has permission to see, not all Open records in the org.
### Inline Editing Permissions
**How It Works:** For components with inline editing (like Data Table), users must have:
* Field-level Edit permission
* Record-level Edit access
* Object-level Edit permission
**What This Means:**
* Even if `editableFields` includes a field, users may not be able to edit it
* Some users might see editable fields while others see read-only fields
* Edit functionality respects field-level security dynamically
***
## Next Steps
You now understand the core concepts needed to build effective Lightning pages with Avonni App Builder Components. Continue your learning journey:
1. **Component Properties Reference** - Quick reference for property syntax and patterns
2. **Common Use Case Patterns** - Pre-built solutions for typical scenarios
3. **Troubleshooting & FAQs** - Solutions when things don't work as expected
4. **Quick Start Guide** - Build your first component with hands-on examples
strike a balance between functionality, performance,Remember: Start simple and add complexity gradually. The most effective Lightning pages balance functionality with performance and user experience.
***
## Appendix: Complete Field References
### User Fields Reference
**Available {{User.FieldName}} Fields:**
Address, Alias, City, CommunityNickname, CompanyName, ContactId, Country, Department, Division, Email, EmployeeNumber, Extension, Fax, FederationIdentifier, FirstName, GeocodeAccuracy, Id, IsActive, LanguageLocaleKey, LastName, Latitude, LocaleSidKey, Longitude, ManagerId, MobilePhone, Phone, PostalCode, ProfileId, Signature, State, Street, TimeZoneSidKey, Title, Username, UserRoleId, UserType
### UserRole Fields Reference
**Available {{UserRole.FieldName}} Fields:**
CaseAccessForAccountOwner, ContactAccessForAccountOwner, DeveloperName, Id, LastModifiedById, LastModifiedDate, MayForecastManagerShare, Name, OpportunityAccessForAccountOwner, RollupDescription
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.avonnicomponents.com/app-builder-components/getting-started/understanding-the-essentials/core-concepts.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.