dbxReport

1. Processing sequence

1. Resolve the report ID, DD, report fields, and optional selection FD.
2. Read and validate filter, sort, direction, page, and selection values.
3. Build one authorized filter definition.
4. Use the same filter for the count and data queries.
5. Load the current page through dbxDB and the DD.
6. Run the record callback for each row.
7. Apply accumulated replacements and render through dbxTPL.

A report is therefore more than a table renderer. It owns one coherent selection and presentation state for a request.

2. Selection FD and trusted query shape

Use an FD for visible filters and their messages. Treat all request values as untrusted. Validate sorting against fixed field and direction allowlists, and derive database filters from normalized values only. Never concatenate request values into SQL.

3. Count and select must agree

Pagination is correct only when the count query and the page query apply the same owner rules, permissions, and normalized filters. Build the filter contract once and pass it to both operations. Changing one side independently produces empty final pages and misleading totals.

4. Report fields

Report fields define column order, labels, formatting, visibility, and optional action or selection columns. Keep domain values separate from their presentation. A callback may calculate a virtual output value, but the template controls the surrounding markup.

Use translated FD messages for labels, empty states, actions, and validation. Stored domain values remain data and are not automatically translated.

5. Record and footer callbacks

The conventional record callback uses the report ID represented by {fid} and the next_record event. It can format values, create signed action URLs, set a nested module marker, and accumulate page totals with add_rep().

Accumulated replacements are available to the footer after all visible rows have run. Use {rpt:col_count} for all columns and {rpt:colspan} for all columns except the last value column. Avoid hard-coded spans.

6. Output modes

Changing the output mode does not change permissions, filters, callbacks, or query behavior.

7. Nested reports

[modul=myInvoices dbx_run1=positions invoice_id={rid}][/modul]

The outer record callback sets this marker for the current invoice. dbxInterpreter executes the module in the current server context and replaces the marker with the inner report. The inner report uses its own ID and does not create a nested HTML form.

For a small, bounded page this produces clear, targeted queries. For very large result sets, load the detail report on demand or design a domain batch through dbxDB; do not introduce a parallel internal HTTP endpoint.

8. Pagination, sorting, and multiple instances

Page numbers, page sizes, sorting, and filters belong to the report state. Preserve them in generated routes and actions. Every report instance needs a unique 1 root so that two reports on the same page keep independent selection, callbacks, totals, pagination, and Ajax targets.

9. Actions and selection

Read-only row navigation uses ordinary authorized links. State-changing GET actions require an action token bound to the route and RID. Bulk actions validate the selected records again on the server and apply DD permissions to every mutation. A checkbox does not grant access.

Use dbxConfirm and dbxAjax for the interaction. Confirmation decides whether to continue; authorization and mutation remain server-side.

10. Ajax behavior

An Ajax filter or page change runs the same report route and replaces only the declared report root. The server returns complete report state, including messages, counts, current selection, and navigation. The non-JavaScript URL must remain usable and equivalent.

11. Acceptance checklist

• Count and select use identical filters and owner restrictions.
• Unknown sort fields and directions are rejected or replaced by safe defaults.
• Empty results, first and last pages, and page-size changes render correctly.
• Record callbacks and footer totals use the correct page or complete-result scope.
• Nested reports cannot read data without their own DD permission.
• Two instances keep independent state and DOM IDs.
• Read actions remain tokenless; state-changing GET actions require a valid bound token.
• Normal navigation and Ajax return equivalent content.
• German and English labels, actions, empty states, and messages are complete.
• Browser console, Missing counters, files/dbxError.log, PHP logs, and system messages remain clean.