Přeskočit na hlavní obsah

Konfigurace - Nastavení modulu

Dokumentace konfigurace modulu Banking - layouty, metadata, překlady a nastavení.

Metadata​

Entity Definitions​

Metadata pro entity jsou uloženy v: Cesta: backend/Resources/metadata/entityDefs/

Bank.json​

Definuje strukturu entity Bank včetně polí, vazeb a indexů.

Klíčová nastavení:

{
  "collection": {
    "orderBy": "createdAt",
    "order": "desc"
  },
  "indexes": {
    "name": {
      "columns": ["name", "deleted"]
    }
  }
}

BankAccount.json​

Definuje strukturu entity BankAccount včetně speciálních polí jako bankAccountNumber a credential.

Klíčová nastavení:

{
  "optimisticConcurrencyControl": false,
  "collection": {
    "textFilterFields": ["name"],
    "fullTextSearch": false
  }
}

BankTransaction.json​

Definuje strukturu entity BankTransaction včetně readonly polí a vazeb na faktury.

Klíčová nastavení:

{
  "collection": {
    "orderBy": "createdAt",
    "order": "desc"
  }
}

Client Definitions​

Metadata pro frontend jsou uložena v: Cesta: backend/Resources/metadata/clientDefs/

Bank.json​

{
  "controller": "controllers/record",
  "iconClass": "fas fa-university",
  "color": "#3498db",
  "boolFilterList": ["usesApi"],
  "relationshipPanels": {
    "bankAccounts": {
      "create": true,
      "select": false
    }
  }
}

Vysvětlení:

  • iconClass: Ikona pro entitu (Font Awesome)
  • color: Barva entity v UI
  • boolFilterList: Rychlé bool filtry
  • relationshipPanels: Konfigurace panelů vztahů

BankAccount.json​

{
  "controller": "controllers/record",
  "iconClass": "fas fa-credit-card",
  "color": "#2ecc71",
  "dynamicLogic": {
    "fields": {
      "iban": {
        "visible": {
          "conditionGroup": [
            {
              "type": "equals",
              "attribute": "type",
              "value": "foreign"
            }
          ]
        }
      }
    }
  },
  "menu": {
    "detail": [
      {
        "label": "Download Transactions",
        "action": "downloadTransactions",
        "acl": "edit"
      }
    ]
  }
}

BankTransaction.json​

{
  "controller": "controllers/record",
  "iconClass": "fas fa-exchange-alt",
  "color": "#e74c3c",
  "boolFilterList": ["invoiceNotFound", "isInvoiceAssigned"],
  "filterList": ["incoming", "outgoing"],
  "defaultFilterData": {
    "primary": "all"
  }
}

Record Definitions​

Cesta: backend/Resources/metadata/recordDefs/

Definují chování záznamů:

  • Before/After save hooks
  • Duplicate check
  • Mandatory fields
  • Read-only fields

ACL Definitions​

Cesta: backend/Resources/metadata/aclDefs/

Definují přístupová práva:

BankAccount.json​

{
  "mandatory": {
    "scopeLevel": {
      "read": "yes",
      "edit": "team",
      "delete": "no",
      "create": "team"
    }
  }
}

Úrovně přístupu:

  • all - Všichni uživatelé
  • team - Pouze týmoví uživatelé
  • own - Pouze vlastní záznamy
  • no - Žádný přístup

Layouts​

List Layouts​

Cesta: backend/Resources/layouts/[Entity]/list.json

Bank List​

[
  {"name": "name", "width": 30},
  {"name": "code", "width": 10},
  {"name": "usesApi", "width": 10},
  {"name": "assignedUser", "width": 15}
]

BankAccount List​

[
  {"name": "name", "width": 20},
  {"name": "bankAccountNumber", "width": 25},
  {"name": "bank", "width": 20},
  {"name": "balance", "width": 15},
  {"name": "enabled", "width": 10}
]

BankTransaction List​

[
  {"name": "transactionDate", "width": 15},
  {"name": "type", "width": 10},
  {"name": "amount", "width": 15},
  {"name": "counterAccountName", "width": 20},
  {"name": "variableSymbol", "width": 15},
  {"name": "isInvoiceAssigned", "width": 10}
]

Detail Layouts​

Cesta: backend/Resources/layouts/[Entity]/detail.json

Definují rozložení detail view s panely.

Bank Detail​

{
  "panels": [
    {
      "name": "overview",
      "label": "Přehled",
      "rows": [
        [{"name": "name"}, {"name": "code"}],
        [{"name": "website"}, {"name": "usesApi"}]
      ]
    },
    {
      "name": "notifications",
      "label": "Notifikace",
      "rows": [
        [{"name": "enableAlertUsers"}],
        [{"name": "users"}],
        [{"name": "notificationTeams"}]
      ]
    }
  ]
}

BankAccount Detail​

{
  "panels": [
    {
      "name": "overview",
      "label": "Přehled",
      "rows": [
        [{"name": "name"}, {"name": "bank"}],
        [{"name": "bankAccountNumber"}, {"name": "type"}],
        [{"name": "iban"}, {"name": "swift"}],
        [{"name": "balance"}, {"name": "enabled"}]
      ]
    },
    {
      "name": "api",
      "label": "API přístup",
      "rows": [
        [{"name": "credential"}]
      ]
    }
  ]
}

BankTransaction Detail​

{
  "panels": [
    {
      "name": "overview",
      "label": "Přehled",
      "rows": [
        [{"name": "type"}, {"name": "transactionDate"}],
        [{"name": "amount"}, {"name": "bankAccount"}],
        [{"name": "transactionType"}]
      ]
    },
    {
      "name": "counterparty",
      "label": "Protiúčet",
      "rows": [
        [{"name": "counterAccountName"}],
        [{"name": "counterBankAccountNumber"}, {"name": "counterBank"}]
      ]
    },
    {
      "name": "symbols",
      "label": "Symboly",
      "rows": [
        [{"name": "variableSymbol"}, {"name": "constantSymbol"}],
        [{"name": "specificSymbol"}]
      ]
    },
    {
      "name": "invoices",
      "label": "Faktury",
      "rows": [
        [{"name": "invoice"}, {"name": "supplierInvoice"}],
        [{"name": "proformaInvoice"}, {"name": "receivedProformaInvoice"}],
        [{"name": "invoiceNotFound"}]
      ]
    }
  ]
}

Filter Layouts​

Cesta: backend/Resources/layouts/[Entity]/filters.json

Definují dostupné filtry v seznamech.

BankTransaction Filters​

{
  "primary": [
    "all",
    "incoming",
    "outgoing",
    "unpaired",
    "invoiceNotFound"
  ],
  "bool": {
    "invoiceNotFound": "Faktura nenalezena",
    "isInvoiceAssigned": "Přiřazeno k faktuře"
  },
  "fields": {
    "transactionDate": {},
    "amount": {},
    "bankAccount": {},
    "type": {},
    "variableSymbol": {}
  }
}

Mass Update Layout​

Cesta: backend/Resources/layouts/[Entity]/massUpdate.json

Definuje pole dostupná pro hromadnou aktualizaci.

[
  "assignedUser",
  "teams"
]

Poznámka: Pro Banking entity je hromadná aktualizace omezená, protože většina polí je readonly.

Překlady (i18n)​

Struktura překladů​

Cesta: backend/Resources/i18n/[locale]/[Entity].json

Podporované lokalizace:

  • cs_CZ - Čeština
  • en_US - Angličtina
  • de_DE - Němčina
  • sk_SK - Slovenština

Formát překladu​

{
  "labels": {
    "Create Bank": "Vytvořit Banka"
  },
  "fields": {
    "name": "Název",
    "bankAccount": "Bankovní účet"
  },
  "links": {
    "bankAccounts": "Bankovní účty"
  },
  "options": {
    "type": {
      "Incoming": "Příchozí",
      "Outgoing": "Odchozí"
    }
  },
  "tooltips": {
    "invoiceNotFound": "Označuje transakce..."
  },
  "messages": {
    "downloadSuccess": "Transakce byly úspěšně staženy"
  }
}

Přidání vlastního překladu​

  1. Vytvořte soubor v custom/Espo/Custom/Resources/i18n/[locale]/Banking.json
  2. Přidejte vlastní překlady:
{
  "messages": {
    "customMessage": "Vlastní zpráva"
  }
}
  1. Použijte v kódu:
this.translate('customMessage', 'messages', 'Banking')

Nastavení (Settings)​

Entity Settings​

Soubor: backend/Resources/metadata/entityDefs/Settings.json

{
  "fields": {
    "bankingEnabled": {
      "type": "bool",
      "default": true
    },
    "bankingAutoDownload": {
      "type": "bool",
      "default": false
    },
    "bankingDownloadInterval": {
      "type": "int",
      "default": 3600,
      "tooltip": true
    },
    "bankingNotificationsEnabled": {
      "type": "bool",
      "default": true
    }
  }
}

Přístup k nastavení​

Backend (PHP)​

$config = $this->getConfig();
$enabled = $config->get('bankingEnabled', true);

Frontend (JS/TS)​

const enabled = this.getConfig().get('bankingEnabled');

Dynamic Logic​

Field Visibility​

{
  "fields": {
    "iban": {
      "visible": {
        "conditionGroup": [
          {
            "type": "equals",
            "attribute": "type",
            "value": "foreign"
          }
        ]
      }
    }
  }
}

Field Required​

{
  "fields": {
    "swift": {
      "required": {
        "conditionGroup": [
          {
            "type": "equals",
            "attribute": "type",
            "value": "foreign"
          }
        ]
      }
    }
  }
}

Field Read-only​

{
  "fields": {
    "balance": {
      "readOnly": {
        "conditionGroup": [
          {
            "type": "isNotEmpty",
            "attribute": "id"
          }
        ]
      }
    }
  }
}

Options Dynamic​

{
  "fields": {
    "credential": {
      "optionsPath": "data.credentialOptions"
    }
  }
}

Formuláře​

Create Form​

Formulář pro vytváření nového záznamu.

Konfigurace: Používá detailSmall.json layout

Edit Form​

Formulář pro editaci existujícího záznamu.

Konfigurace: Používá detail.json layout

Quick Create​

Rychlé vytvoření z jiných entit.

Příklad: Vytvoření BankAccount přímo z Bank detail view

Relationship Panels​

Konfigurace panelů​

{
  "relationshipPanels": {
    "bankAccounts": {
      "select": false,
      "create": true,
      "view": "views/record/panels/relationship",
      "recordListView": "views/record/list",
      "layout": "listForBank"
    }
  }
}

Parametry:

  • select: Povolit výběr existujících
  • create: Povolit vytváření nových
  • view: Custom view pro panel
  • layout: Vlastní layout pro seznam

Validation Rules​

Field Validation​

Bank Account Number​

{
  "bankAccountNumber": {
    "type": "bankAccountNumber",
    "pattern": "^\\d{6}-\\d{10}\\/\\d{4}$",
    "maxLength": 30
  }
}

IBAN​

{
  "iban": {
    "type": "varchar",
    "pattern": "^[A-Z]{2}\\d{2}[A-Z0-9]+$",
    "maxLength": 100
  }
}

SWIFT​

{
  "swift": {
    "type": "varchar",
    "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
    "maxLength": 11
  }
}

Export/Import​

Export Configuration​

{
  "exportDisabled": false,
  "exportFields": [
    "name",
    "bankAccountNumber",
    "iban",
    "balance"
  ]
}

Import Configuration​

{
  "importDisabled": true
}

Poznámka: Import je zakázán pro BankTransaction, protože transakce se importují automaticky z bank.

Stream (Aktivita)​

Stream Configuration​

{
  "stream": true,
  "statusStyles": {
    "Incoming": "success",
    "Outgoing": "danger"
  }
}

Doporučené postupy​

Customizace layoutů​

  1. Nikdy neupravujte přímo v modulech

    • Používejte Custom adresář
    • Nebo upravujte přes Administration UI

  2. Backup před úpravou

    • Zálohujte metadata před změnami
    • Testujte na vývojovém prostředí

  3. Konzistence

    • Dodržujte jednotný styl layoutů
    • Používejte konzistentní šířky sloupců

Překlady​

  1. Používejte translation keys

    • Vždy používejte translation keys místo hardcoded textů
    • Poskytujte překlady pro všechny podporované jazyky

  2. Konzistence v názvosloví

    • Používejte stejné termíny napříč modulem
    • Dodržujte firemní terminologii

Metadata​

  1. Testujte změny

    • Vždy po změně metadata clear cache
    • Rebuild aplikace

  2. Dokumentujte custom pole

    • Vyplňte tooltip pro všechny custom pole
    • Poskytněte description

Poznámky​

  • Po změně metadata je nutné provést Rebuild (Administration → Rebuild)
  • Clear cache po změně layoutů: Administration → Clear Cache
  • Dynamic logic se vyhodnocuje v real-time na frontendu
  • Všechny metadata změny by měly být verzovány (Git)