espocrm/custom/CUSTOM_DIRECTORY.md

EspoCRM Custom Directory - Vollständige Übersicht

Dieses Dokument beschreibt die vollständige Struktur aller Custom-Verzeichnisse in EspoCRM. Für Workflow-Management, Formula-Scripts und andere Funktionalitäten siehe die Hauptdokumentation in /README.md.

Vollständige Verzeichnisstruktur

custom/                                 # Backend Customizations
├── Espo/
│   ├── Custom/                        # Custom Entitäten, Services, Controller
│   │   ├── Classes/                   # Custom PHP-Klassen
│   │   │   └── FormulaFunctions/      # Custom Formula-Funktionen
│   │   ├── Controllers/               # Custom Controller
│   │   ├── Services/                  # Custom Services
│   │   ├── Repositories/              # Custom Repositories
│   │   └── Resources/
│   │       ├── metadata/              # Entity-, Field-, Client-Definitionen
│   │       │   ├── entityDefs/        # Entity-Definitionen (Felder, Links)
│   │       │   ├── clientDefs/        # Frontend-Konfigurationen
│   │       │   ├── selectDefs/        # Filter-Definitionen
│   │       │   ├── scopes/            # Entity-Scopes
│   │       │   ├── fields/            # Globale Feld-Definitionen
│   │       │   ├── formula/           # Formula-Scripts pro Entity
│   │       │   ├── recordDefs/        # Record-spezifische Logik
│   │       │   ├── aclDefs/           # Zugriffsrechte
│   │       │   └── app/               # App-weite Konfigurationen
│   │       │       ├── formula.json   # Formula-Funktions-Registrierung
│   │       │       └── client.json    # CSS/JS-Registrierung
│   │       ├── layouts/               # UI-Layout-Definitionen
│   │       │   └── {Entity}/
│   │       │       ├── detail.json    # Detail-View-Layout
│   │       │       ├── list.json      # List-View-Layout
│   │       │       ├── edit.json      # Edit-View-Layout
│   │       │       └── bottomPanelsDetail.json  # Bottom-Panels
│   │       └── i18n/                  # Übersetzungen
│   │           ├── de_DE/             # Deutsche Übersetzungen
│   │           │   └── {Entity}.json  # Labels, Links, Tooltips
│   │           └── en_US/             # Englische Übersetzungen (FALLBACK!)
│   │               └── {Entity}.json  # MUSS vollständig sein
│   └── Modules/                       # Custom Module (gekapselt)
│       └── {ModuleName}/
│           └── Resources/             # Gleiche Struktur wie Custom/Resources/
├── scripts/                           # Wartungs- und Verwaltungs-Scripts
│   ├── check_and_rebuild.sh          # Validierung + Rebuild + Rechteprüfung
│   └── workflow_manager.php           # Workflow-Verwaltung (list, import, export, delete)
└── workflows/                         # Workflow-Definitionen (versioniert)
    ├── README.md                      # Workflow-Format-Dokumentation
    └── *.json                         # Workflow-Definitionen (Simple & BPM)

client/custom/                         # Frontend Customizations
├── css/                               # Custom CSS-Stylesheets
│   └── *.css                          # Muss in app/client.json registriert werden
├── src/
│   ├── modules/                       # AMD JavaScript-Module
│   │   └── *.js                       # Wiederverwendbare Logik (z.B. Calculator)
│   └── views/                         # Custom Backbone.js Views
│       └── {entity}/
│           ├── fields/                # Custom Field Views
│           │   └── {fieldname}.js     # Erweitert Standard-Field-Views
│           ├── detail.js              # Custom Detail-View
│           ├── edit.js                # Custom Edit-View
│           └── list.js                # Custom List-View
├── modules/                           # Third-Party Extensions
│   ├── advanced/                      # Advanced Pack Module
│   ├── link-button/                   # Link-Button Extension
│   └── crm/                           # CRM Module
└── res/                               # Custom Frontend-Ressourcen
    └── templates/                     # Handlebars-Templates

Backend Customizations (custom/Espo/)

custom/Espo/Custom/Resources/metadata/

Dies ist das Herzstück der EspoCRM-Customization. Alle JSON-Dateien hier werden rekursiv mit Core-Definitionen gemerged.

entityDefs/{Entity}.json

Definiert Entitäten mit Feldern, Beziehungen, Indizes:

• fields - Feldtypen, Validierungen, Optionen
• links - Relationships (belongsTo, hasMany, hasOne)
• collection - Sortierung, Standard-Filter
• indexes - Datenbank-Performance-Optimierung

Wichtig bei Relationships:

• Bei hasMany-Relationships BEIDE Seiten definieren
• relationName muss identisch sein
• foreign zeigt auf den Link-Namen der Gegenseite
• Fehlt eine Seite: "404 Link does not exist"-Fehler

clientDefs/{Entity}.json

Frontend-Konfiguration für Entitäten:

• views - Custom Views (detail, list, edit)
• controller - Custom Controller-Logik
• filterList - Report-Filter (mit __APPEND__)
• sidePanels - Report-Panels
• relationshipPanels - Relationship-Panel-Konfiguration

layouts/{Entity}/{LayoutType}.json

UI-Layout-Definitionen:

• Arrays von Panels mit label und rows
• rows sind Arrays von Zellen mit {"name": "fieldName"}
• Layout-Typen: detail, list, edit, kanban, bottomPanelsDetail

formula/{Entity}.json

Formula-Scripts für Validierung und Berechnung:

• beforeSaveApiScript - Vor dem Speichern (ab v7.5+)
• afterSaveScript - Nach dem Speichern
• NICHT in entityDefs ablegen! (funktioniert nicht)

i18n/{Language}/{Entity}.json

Mehrsprachige Labels und Tooltips:

• fields - Feld-Labels
• links - Relationship-Labels (identisch mit fields!)
• tooltips - Hilfe-Texte für Felder
• labels - Sonstige UI-Texte
• presetFilters - Report-Filter-Labels

KRITISCH: en_US ist Fallback-Sprache und MUSS vollständig sein!

custom/Espo/Custom/Classes/

Custom PHP-Klassen für erweiterte Logik:

FormulaFunctions/{GroupName}/{FunctionName}Type.php

Custom Formula-Funktionen:

• Namespace: Espo\Custom\Classes\FormulaFunctions\{GroupName}
• Muss BaseFunction erweitern
• Registrierung in app/formula.json erforderlich

Beispiel: IBAN-Validierung, Custom Berechnungen

Frontend Customizations (client/custom/)

client/custom/src/modules/

AMD JavaScript-Module für wiederverwendbare Logik:

define('custom:modules/my-module', [], function () {
    return {
        myFunction: function(params) {
            // Wiederverwendbare Logik
        }
    };
});

Verwendung: define('path/to/view', ['custom:modules/my-module'], function (MyModule) { ... })

Beispiel: rvg-calculator.js - RVG-Gebührenberechnung

client/custom/src/views/

Custom Backbone.js Views für Entity-spezifisches UI-Verhalten:

define('custom:views/entity/fields/fieldname', ['views/fields/base'], function (Dep) {
    return Dep.extend({
        setup: function () {
            Dep.prototype.setup.call(this);
            this.listenTo(this.model, 'change:field1', this.onFieldChange);
            this.listenTo(this.model, 'sync', this.onSync); // Initial load
        },
        onFieldChange: function () {
            // Reaktive Logik
        }
    });
});

Wichtige Patterns:

• listenTo(model, 'sync', callback) - Initial berechnung beim Laden
• listenTo(model, 'change:field', callback) - Reaktivität
• calculating Flag verhindert Rekursion bei model.set()

Registrierung in entityDefs:

{
    "fields": {
        "fieldName": {
            "type": "varchar",
            "view": "custom:views/entity/fields/fieldname"
        }
    }
}

client/custom/css/

Custom CSS-Stylesheets für UI-Anpassungen:

Datei erstellen: client/custom/css/my-styles.css

Registrieren in custom/Espo/Custom/Resources/metadata/app/client.json:

{
    "cssList": [
        "__APPEND__",
        "client/custom/css/my-styles.css"
    ]
}

CSS-Targeting-Strategien:

• Feld-spezifisch: .cell[data-name="fieldName"]
• Entity-spezifisch: body[data-controller="EntityName"]
• View-spezifisch: .detail, .edit, .list
• Label vs. Value: .label-text vs. .numeric-text

Nach CSS-Änderungen: Rebuild + Browser Hard Refresh (Ctrl+Shift+R)

client/custom/modules/

Third-Party Extensions und zusätzliche Module:

• advanced/ - Advanced Pack (Reports, Workflows, BPM)
• link-button/ - Custom Link-Button Extension
• crm/ - CRM-Erweiterungen

Diese werden meist von Extensions installiert und sollten nicht manuell bearbeitet werden.

Scripts und Tools (custom/scripts/)

check_and_rebuild.sh

Zentrale Schnittstelle für Validierung und Rebuild:

Funktionen:

• ✓ JSON-Syntax-Validierung aller .json Dateien
• ✓ Dateirechte-Prüfung (www-data:www-data)
• ✓ System-Checks (Cache, Logs)
• ✓ Automatischer Rebuild bei Fehlerfreiheit
• ✓ Fehler-Reporting mit Zeilennummern

Verwendung:

./custom/scripts/check_and_rebuild.sh

Ausgabe:

• ✓ Grün: Alles in Ordnung, Rebuild erfolgreich
• ⚠ Gelb: Warnungen, Rebuild wird trotzdem ausgeführt
• ✗ Rot: Fehler, Rebuild wird NICHT ausgeführt

Dieses Script sollte IMMER verwendet werden statt manueller Rebuild-Befehle!

workflow_manager.php

Kommandozeilen-Tool für Workflow-Verwaltung. Details siehe /README.md Abschnitt "Workflow-Verwaltung".

Workflows (custom/workflows/)

Versionierte Workflow-Definitionen als JSON:

• Simple Workflows (regel-basiert)
• BPM Flowcharts (BPMN 2.0)

Format-Dokumentation: custom/workflows/README.md

Verwaltung: Über workflow_manager.php (siehe /README.md)

Best Practices

Entwicklungs-Workflow

1. Backend-Änderungen (Metadata, PHP):

   • Dateien in custom/Espo/Custom/ bearbeiten
   • ./custom/scripts/check_and_rebuild.sh ausführen
   • Logs prüfen: data/logs/espo-*.log

2. Frontend-Änderungen (JS, CSS):

   • Dateien in client/custom/ erstellen/bearbeiten
   • In app/client.json registrieren (CSS) oder in entityDefs referenzieren (Views)
   • ./custom/scripts/check_and_rebuild.sh ausführen
   • Browser Hard Refresh (Ctrl+Shift+R)

3. Workflows:

   • JSON in custom/workflows/ erstellen
   • Mit workflow_manager.php import einspielen
   • Im Admin-Interface testen

Versionskontrolle

Git committen:

• Alle JSON-Dateien in custom/
• Alle JavaScript/CSS-Dateien in client/custom/
• Alle Workflows in custom/workflows/
• Scripts in custom/scripts/

Nicht committen:

• data/cache/ - Cache-Verzeichnis
• data/logs/ - Log-Dateien
• data/upload/ - Hochgeladene Dateien

Dateirechte

Das check_and_rebuild.sh Script prüft automatisch Dateirechte. Falls manuelle Korrektur nötig:

sudo chown -R www-data:www-data custom/
sudo find custom/ -type f -name "*.json" -exec chmod 664 {} \;
sudo find custom/ -type d -exec chmod 775 {} \;

Naming Conventions

Entities: PascalCase mit Präfix (z.B. CVmhMietverhltnis, CBeteiligte)

Links: camelCase mit Präfix (z.B. contactsMietverhltnis, vmhMieterbeteiligte)

relationName: Kombination beider Entities (z.B. cVmhMietverhltnisContact)

Workflows: kebab-case mit Präfix (z.B. vmh-erstberatung-abschliessen.json)

Views: Entity-Pfad + Funktion (z.B. custom:views/c-vmh-erstgespraech/fields/rvg-calculated)

CSS: kebab-case mit Kontext (z.B. erstgespraech-highlight.css)

Häufige Fehler und Lösungen

"Link does not exist" (404)

Ursache: Unvollständige hasMany-Relationship Lösung: Beide Seiten der Relationship in entityDefs definieren

Tooltip zeigt nur Feldnamen

Ursache: Fehlerhafte oder fehlende en_US i18n-Datei Lösung: Tooltips in ALLEN Sprachen definieren (en_US ist Fallback!)

Formula-Script wird nicht ausgeführt

Ursache: Script in entityDefs statt formula/ Lösung: Separate formula/{Entity}.json Datei erstellen

CSS-Änderungen nicht sichtbar

Ursache: Browser-Cache oder fehlende Registrierung Lösung: In app/client.json registrieren + Rebuild + Hard Refresh

"Permission denied" bei Layout-Bearbeitung

Ursache: Falsche Dateirechte (root statt www-data) Lösung: ./custom/scripts/check_and_rebuild.sh führt automatisch Rechteprüfung durch

Weiterführende Dokumentation

• Hauptdokumentation: /README.md - Workflow-Management, Formula-Scripts, Reports, Troubleshooting
• Workflow-Formate: /custom/workflows/README.md - JSON-Format-Spezifikationen
• EspoCRM Docs: https://docs.espocrm.com