4D Development Expert (v21)

Skill Version

4D Version: v21
Skill Version: 1.0
Docs: Full official 4D v21 documentation embedded in docs/ (3,387 files)

This skill targets 4D v21 specifically. Do not assume features from other versions exist unless verified in the embedded documentation.

How to Use This Skill

CRITICAL: For any 4D task, ALWAYS prefer reading the embedded documentation files (docs/) over relying on training data. The docs/ folder contains the authoritative 4D v21 reference.

Workflow:

Check this file for critical rules and routing
Read the relevant references/ file for curated knowledge and patterns
If more detail is needed, read the specific docs/ file pointed to by the reference
For edge cases, use grep to search across docs/
Only fall back to training data if docs/ doesn't cover the topic

Priority reading: Always check references/manual-insights.md — it contains real-world corrections from code reviews that override documentation.

Local Conventions

Before providing 4D guidance, check if a local/ directory exists in this skill folder with project-specific conventions:

ls local/*.md 2>/dev/null

If files exist, read them first. The local/ directory (gitignored) can contain:

Company-specific naming conventions and documentation standards
Project-specific database schemas
Version overrides (e.g., if project uses 4D v19.2 instead of v21)

Critical Syntax Rules

These are the most common sources of bugs in 4D code. Know them by heart.

1. Assignment vs Comparison

// WRONG: = is comparison, returns True/False
$name = Request("Enter name")        // Compares, doesn't assign!
If ($input = Request("Name"))        // WRONG: compares, doesn't assign

// CORRECT: := is assignment
$name:=Request("Enter name")        // Assigns
$input:=Request("Name")
If ($input # "")                     // Then compare separately

Rule: := assigns. = compares. Never mix them.

2. Object Properties Are Case-Sensitive

// Variables: case-INSENSITIVE
$MyVar:="test"
$myvar:="changed"            // Same variable!

// Object properties: case-SENSITIVE
$obj.Name:="John"
$obj.name:="Jane"            // Different properties!

3. Collection vs Array Indexing

// Collections: 0-based
$col:=New collection("A"; "B"; "C")
$first:=$col[0]              // "A"

// Arrays: 1-based with special element zero
ARRAY TEXT($arr; 3)
$arr{1}:="A"                 // First element
$arr{0}:="default"           // Special element zero

4. Null Queries Require Literal Syntax

// WRONG: Null as placeholder doesn't work
$result:=ds.Users.query("email = :1"; Null)

// CORRECT: literal null in query string
$result:=ds.Users.query("email = null")
$active:=ds.Users.query("email != null")

5. Linked Collection Queries

// WRONG: conditions can match DIFFERENT collection elements
ds.Users.query("projects[].status = 'active' AND projects[].budget > 1000")

// CORRECT: [a] links conditions to the SAME element
ds.Users.query("projects[a].status = 'active' AND projects[a].budget > 1000")

6. Numeric Object Properties Are Always Real

$obj:=New object("count"; 5)
Value type($obj.count)  // Returns Is real, NEVER Is longint

7. Decimal Separator Is Always Period

$price:=19.99    // CORRECT — always period
$price:=19,99    // WRONG — two separate numbers!

8. 4D has a strict left-to-right precedence

if ($length > 1+$i) // Runtime error: $length>1 -> true -> true+$i -> error
if ($length > (1+$i)) // No error

$result:=3+4*5 // 35
$result:=3+(4*5) // 23

Quick Decision Router

By Task

| Task | Read First | Then If Needed | |------|-----------|----------------| | Syntax errors, operators | language-syntax.md | docs/Concepts/operators.md | | Data types, conversions | data-types.md | docs/Concepts/data-types.md | | ORDA, entity classes | orda-modern.md | docs/ORDA/ordaClasses.md | | Database queries | query-patterns.md | docs/API/DataClassClass.md | | Error handling | error-handling.md | docs/Concepts/error-handling.md | | Legacy/classic code | classic-patterns.md | docs/Concepts/arrays.md | | Forms, events, UI | forms-and-ui.md | events-index.md | | Web server, REST API | web-and-rest.md | rest-index.md | | Specific class API | api-index.md | docs/API/{ClassName}Class.md | | Specific command | commands-index.md | docs/commands/{name}.md | | Legacy command | legacy-commands-index.md | docs/commands-legacy/{name}.md |

By Error / Symptom

| Error or Symptom | Read | |-----------------|------| | "Type mismatch" or wrong type | data-types.md | | "Cannot use = to assign" / silent assignment bug | language-syntax.md | | Query returns wrong results | query-patterns.md | | "Null query" not working | manual-insights.md | | Entity/EntitySelection methods | orda-modern.md then api-index.md | | Form events not firing | forms-and-ui.md then events-index.md | | Process variables not working | classic-patterns.md | | REST endpoint 404 or auth error | web-and-rest.md | | Transaction or save error | error-handling.md | | local keyword confusion | manual-insights.md | | Need to find a specific 4D command | commands-index.md | | Need to find a legacy command | legacy-commands-index.md |

Docs Navigator

The docs/ folder contains the full official 4D v21 documentation (3,387 files, 48MB). Use this section to find the right file.

Category Quick Lookup

| Need | Directory | File Pattern | Example Path | |------|-----------|-------------|--------------| | Class API reference | docs/API/ | {Class}Class.md | docs/API/CollectionClass.md | | ORDA concepts | docs/ORDA/ | {topic}.md | docs/ORDA/entities.md | | Modern commands | docs/commands/ | {command-name}.md | docs/commands/dialog.md | | Commands by theme | docs/commands/theme/ | {Theme}.md | docs/commands/theme/JSON.md | | Language concepts | docs/Concepts/ | {topic}.md | docs/Concepts/classes.md | | REST endpoints | docs/REST/ | ${endpoint}.md | docs/REST/$filter.md | | Form events | docs/Events/ | on{Event}.md | docs/Events/onClicked.md | | Form objects | docs/FormObjects/ | {type}_overview.md | docs/FormObjects/listbox_overview.md | | Web server | docs/WebServer/ | {topic}.md | docs/WebServer/sessions.md | | Legacy commands | docs/commands-legacy/ | {command-name}.md | docs/commands-legacy/alert.md | | Settings | docs/settings/ | {topic}.md | docs/settings/web.md | | Project structure | docs/Project/ | {topic}.md | docs/Project/architecture.md | | AI Kit | docs/aikit/ | various | docs/aikit/ | | ViewPro | docs/ViewPro/ | various | docs/ViewPro/ | | WritePro | docs/WritePro/ | various | docs/WritePro/ |

Search Patterns

When you need to find something specific across docs/:

# Find a command by name
grep -rl "title: CommandName" docs/commands/ docs/commands-legacy/

# Find a class method
grep -rl "\.methodName" docs/API/

# Find usage of a specific function
grep -rl "functionName" docs/ --include="*.md"

# Find a form event
ls docs/Events/on*.md

# Find a form object type
ls docs/FormObjects/*_overview.md

# Find a REST endpoint
ls docs/REST/\$*.md

# Find settings for a topic
grep -rl "keyword" docs/settings/

# Find a legacy command by theme
grep -rl "CommandName" docs/commands/theme/

Index Files

For structured navigation of large categories, read these generated indexes:

| Index | Content | Files Indexed | |-------|---------|---------------| | api-index.md | All API classes with key methods | 42 | | commands-index.md | Modern commands + theme categories | 65 + 76 | | concepts-index.md | Language concept files | 29 | | orda-index.md | ORDA documentation structure | 10 | | rest-index.md | REST API endpoints | 36 | | events-index.md | Form and system events | 61 | | form-objects-index.md | Form object types | 54 | | webserver-index.md | Web server documentation | 14 | | legacy-commands-index.md | Legacy commands by theme | 1,211 | | all-categories-index.md | Master navigation | 32 categories |

Reference Files Guide

Curated Knowledge (hand-written, with code examples)

| File | Covers | Priority | |------|--------|----------| | language-syntax.md | Assignment, operators, control flow, methods, classes, strings, formulas | High — read for any syntax question | | data-types.md | All types, conversions, null/undefined, collections, objects, pointers | High — read for type errors | | orda-modern.md | ORDA architecture, entity classes, computed attributes, shared objects, signals | High — read for new feature development | | query-patterns.md | Query syntax, placeholders, null queries, linked collections, formulas, performance | High — read for any query work | | error-handling.md | Try/Catch, ON ERR CALL, transactions, Throw, logging | Medium — read when handling errors | | classic-patterns.md | Arrays, process variables, pointers, sets, migration strategies | Medium — read for legacy code | | forms-and-ui.md | Forms, events, form objects, list boxes, subforms, form classes | Medium — read for UI work | | web-and-rest.md | Web server, REST API, HTTP handlers, sessions, authentication | Medium — read for web/REST work | | manual-insights.md | Real-world corrections from code reviews — overrides other sources | Always check for edge cases |

Common Workflows

New Feature Development:

orda-modern.md for architecture patterns
query-patterns.md for database operations
error-handling.md for robust error management
Specific docs/API/ files for class method details

Legacy Code Maintenance:

classic-patterns.md for understanding legacy code
orda-modern.md for modernization options
language-syntax.md for syntax questions

Debugging:

Check Critical Syntax Rules above first
language-syntax.md for syntax errors
data-types.md for type errors
query-patterns.md for query issues
manual-insights.md for known gotchas

Web/REST Development:

web-and-rest.md for server and REST patterns
orda-modern.md for exposed functions
rest-index.md for specific endpoint docs

External Resources

When the embedded docs don't cover your case:

Official docs: https://developer.4d.com/docs/
Community forum: https://discuss.4d.com/
Blog (feature deep-dives): https://blog.4d.com/
GitHub depot (code examples): https://github.com/4d-depot