Module Quick Start

1. Target and file tree

dbx/modules/myInvoices/
├── myInvoices.class.php
├── include/             Domain service and fixtures
├── dd/                  complete TABLE/FIELDS/INDEXES DDs
├── fd/                  form and report fields
├── tpl/htm/ and help/  domain templates and help
├── js/ and tpl/css/    module-specific assets only
├── tests/               contract and integration tests
└── dbx.package.json

Use PascalCase for classes and snake_case for methods, properties and local variables. New independent classes begin with declare(strict_types=1);.

2. Keep routers small

$run = (string)dbx()->get_modul_var('dbx_run1', 'report', 'parameter|max=32');
$service = dbx()->get_include_obj('myInvoicesService', 'myInvoices');

switch ($run) {
    case 'form':
    case 'edit':
        return $service->form();
    case 'delete':
        return $service->delete();
    default:
        return $service->report();
}

This is a shortened version of the real entry point in myInvoices.class.php. The router selects one domain method and contains neither data access nor HTML. Check group permissions exclusively through dbx()->has_group().

3. Access data exclusively through dbxDB and DD

$db = dbx()->get_system_obj('dbxDB');
$record = $db->select1('myInvoices|invoice', array('id' => $id), '*', 0);
$db->update('myInvoices|invoice', $data, array('id' => $id));

DDs remain complete and directly readable. After a new or amended DD has been written with dbxDD, synchronize it from DD to the database. Only the successful sync completes the structural change. Audit fields must be managed by dbxDB.

4. Form and report on public APIs

• Form: dbxForm with FD. Form ID is UI state identity, not template name. The module master template includes {form:bar}, {form:message} and {form:footer} exactly once.
• Report: Standard tabular lists use the dbxReport default template. Data source, action, record, RID, mode and actions are set via named methods.
• Actions: configure standard actions through set_table_actions().
• Count values: pass the filtered result count and the unfiltered total count separately. The displayed Total count must not change when a search filter is applied.
• Mobile: Tables remain horizontally scrollable; a meaningful card view uses field labels and dbx-report-mobile-cards.

5. Templates, Assets and State

• Look up templates in the target module and then in dbx.
• No embedded <style> or <script>. CSS is below tpl/css/, JavaScript below js/ and is registered once via the asset/feature mechanism.
• No direct access to $_SESSION. UI state uses the relevant state service or the session/remember API.
• Ajax requests, confirmations and windows use the existing dbxapp components; the normal request remains the fallback.

6. dbxKi response for a module change

A dbxKi module order delivers reference/25_Verbindliches_Modulhandbuch.md, reference/KI-TEMPLATES.md and reference/myInvoices/. The AI copies auftrag.contract.json unchanged and fills only the declared outputs:

{
  "outputs": {
    "module.changes": [
      {"action":"module.file.write","params":{"path":"include/myExampleService.class.php","content":"<?php ..."}},
      {"action":"module.dd.sync","params":{"dd":"example"}}
    ],
    "change_log": {
      "summary":"Added a filterable list to the example module",
      "details":"The new report uses a DD, dbxDB, and the dbxReport standard.",
      "resources":["dbx/modules/myExample/include/myExampleService.class.php","dbx/modules/myExample/dd/example.dd.php"]
    }
  }
}

dbxKi generates the plan itself, shows a preview and writes the change log only after successful atomic execution.

7. Verification and acceptance

1. Check PHP and JavaScript syntax.
2. Test DD→DB-Sync and idempotent fixtures via the dbxapp APIs.
3. Normal and Ajax execution, rights, action tokens, error cases and multiple instances test.
4. Check desktop and mobile, filter, pagination, total/hit count and keyboard focus.
5. Run focused module contract and integration tests, then complete the full SelfTest.
6. After success, write exactly one understandable change log entry for the logical block.