4d-v21

name

4d-v21

description

Comprehensive 4D v21 development expert with embedded official documentation. Covers ORDA patterns, entity classes, data model classes, queries, classic methods, data types, error handling, forms, events, web server, and REST API. Use when working with 4D files (.4dm), 4D language questions, 4D project structure, entity classes, ORDA queries, database operations, form development, web server configuration, REST API usage, or any 4D-specific syntax issue. Includes full official 4D v21 documentation for on-demand retrieval. Triggers on: .4dm files, 4D code, ORDA, entity selection, dataclass, 4D query, 4D form, 4D web server, 4D REST, 4D command, 4D collection, 4D object.

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:

1. Check this file for critical rules and routing
2. Read the relevant references/ file for curated knowledge and patterns
3. If more detail is needed, read the specific docs/ file pointed to by the reference
4. For edge cases, use grep to search across docs/
5. 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:

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

Legacy Code Maintenance:

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

Debugging:

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

Web/REST Development:

1. web-and-rest.md for server and REST patterns
2. orda-modern.md for exposed functions
3. 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