# Naming Conventions

## Critical Rules

### Primary Keys: ALWAYS "pKey"

**Rule:** Primary key fields MUST be named `pKey` (not `id`, `key`, or other variants)

**Why:** Framework convention for identifying primary keys across all object types

**Applies to:**

-   BusinessObject SimpleProperty with `id="true"`
-   ListItem SimpleProperty with `id="true"`
-   DataSource Attribute mapping to Salesforce Id field

**Examples:**

```xml
<!-- ListItem -->
<SimpleProperty id="true" name="pKey" type="DomPKey" storable="false" dataSourceProperty="pKey" />

<!-- DataSource -->
<Attribute name="pKey" table="Opportunity" column="Id" />

<!-- BusinessObject -->
<SimpleProperty id="true" name="pKey" type="DomPKey" storable="false" dataSourceProperty="pKey" />
```

---

## File Naming Conventions

### DataSource Files

**Pattern:** `Ds{Type}{ObjectName}_sf.datasource.xml`

| Prefix | Object Type    | Example                                            |
| ------ | -------------- | -------------------------------------------------- |
| `DsBo` | BusinessObject | `DsBoOpportunity_sf.datasource.xml`                |
| `DsLo` | ListObject     | `DsLoOpportunityForStoreCockpit_sf.datasource.xml` |
| `DsLu` | LookupObject   | `DsLuOrderer_sf.datasource.xml`                    |

### BusinessObject Files

**Pattern:** `{ObjectName}.businessobject.xml`

```
BO/BoOpportunity/
  ├── BoOpportunity.businessobject.xml
  └── Mv2/
      ├── BoOpportunity.CustomMethod.bl.js
      └── LoadAsync/
```

### ListObject Files

**Pattern:** `{ObjectName}.listobject.xml` + `{ItemName}.listitem.xml`

```
BO/LoOpportunityForStoreCockpit/
  ├── LoOpportunityForStoreCockpit.listobject.xml
  ├── LiOpportunityForStoreCockpit.listitem.xml
  └── Mv2/
```

### Process Files

**Pattern:** `{Module}_{Screen}Process.processflow.xml`

**Fully Qualified Name in XML:**

```xml
<Process name="Opportunity::OverviewProcess" ...>
```

### UI Files

**Pattern:** `{Module}_{Screen}UI.userinterface.xml`

**Fully Qualified Name in XML:**

```xml
<UIDescription name="Opportunity::OverviewUI" ...>
```

### Business Logic Files

**Pattern:** `{ObjectName}.{MethodName}.bl.js`

**Lifecycle methods in subfolders:**

```
Mv2/
  ├── ObjectName.CustomMethod.bl.js
  ├── LoadAsync/
  │   ├── ObjectName.BeforeLoadAsync.bl.js
  │   └── ObjectName.AfterLoadAsync.bl.js
  ├── SaveAsync/
  │   ├── ObjectName.BeforeSaveAsync.bl.js
  │   └── ObjectName.AfterSaveAsync.bl.js
  └── DoValidateAsync/
```

---

## Property Naming Conventions

### Foreign Keys

**Pattern:** End with `Id` or `PKey`

```xml
<Attribute name="accountId" table="Opportunity" column="AccountId" />
<Attribute name="ownerPKey" table="Opportunity" column="OwnerId" />
<Attribute name="customerPKey" table="Order__c" column="Customer__c" />
```

**Rule:**

-   Use `PKey` suffix for Salesforce Ids (18-character)
-   Use `Id` suffix for other identifiers

### Descriptive Business Names

```xml
<Attribute name="stageName" table="Opportunity" column="StageName" />
<Attribute name="closeDate" table="Opportunity" column="CloseDate" />
<Attribute name="amount" table="Opportunity" column="Amount" />
<Attribute name="opportunityName" table="Opportunity" column="Name" />
```

**Avoid:**

-   Generic names like `field1`, `value`, `data`
-   Database column names when business names are clearer
-   Abbreviations unless universally understood

---

## Process Context Variable Naming

### Cockpit Card Variables

**Pattern:** `Card{CardName}_{Purpose}`

```xml
<Declaration name="CardOpportunities_List" type="LoOpportunityForStoreCockpit" />
<Declaration name="CardOpportunities_InformationText" type="String" />
<Declaration name="CardOpportunities_DataLoaded" type="DomBool" />
<Declaration name="CardOpportunities_DisplayedSubcomponentName" type="String" />
```

### Standard Variable Purposes

-   `_List` - The list object
-   `_InformationText` - Info text for card header
-   `_DataLoaded` - Boolean loading flag
-   `_DisplayedSubcomponentName` - Display control (MANDATORY)
-   `_ContextMenuList` - Context menu items
-   `_Detail` - Selected detail object

---

## Action Naming

### Pattern: `{Entity}_{Verb}{Object}`

```xml
<Action name="CardOpportunities_LoadData" ...>
<Action name="CardOpportunities_GetInfo" ...>
<Action name="CardOpportunities_SetDataLoaded" ...>
<Action name="CardOpportunities_ItemSelected" ...>
```

### Common Verbs

-   `Create` - Create new instance
-   `Load` - Load data
-   `Save` - Save changes
-   `Get` - Retrieve value/info
-   `Set` - Set value
-   `Assign` - Assign value to variable
-   `Validate` - Run validation
-   `Calculate` - Compute value

---

## Event Naming

### Pattern: `{element}_{action}`

```xml
<Event name="cardOpportunities_linkBarButtonPressed" action="..." />
<Event name="cardOpportunities_itemSelected" action="..." />
<Event name="completeCall" action="..." />
```

---

## Module Organization

### Standard Folder Structure

```
src/{ModuleName}/
  ├── BO/              # Business Objects
  │   ├── Bo{Name}/
  │   ├── Lo{Name}/
  │   └── Lu{Name}/
  ├── DS/              # DataSources
  │   ├── DsBo{Name}_sf.datasource.xml
  │   ├── DsLo{Name}_sf.datasource.xml
  │   └── DsLu{Name}_sf.datasource.xml
  └── PR/              # Processes & UI
      └── {Module}_{Screen}/
          ├── {Module}_{Screen}Process.processflow.xml
          └── {Module}_{Screen}UI.userinterface.xml
```

---

## Case Conventions

| Convention | Used For                                  | Example                               |
| ---------- | ----------------------------------------- | ------------------------------------- |
| PascalCase | Object names, File names, Action names    | `BoOpportunity`, `LoadCustomerDetail` |
| camelCase  | Properties, Variables, Parameters, Events | `stageName`, `itemSelected`           |
| UPPER_CASE | Constants, Domain types                   | `DomPKey`, `DomBool`                  |

---

## Anti-Patterns (Avoid)

-   Generic names: `temp`, `data`, `value`, `item`
-   Abbreviations: `custPk`, `ordDt`, `qty`
-   Inconsistent casing: `customerPKey` vs `CustomerPkey`
-   Missing prefixes: Just `Opportunity` instead of `BoOpportunity`
-   Wrong separators: `Card-Opportunities` or `Card.Opportunities`

---

_This documentation is maintained by the Modeler CLI plugin and refreshed on workspace upgrade._