# CBX — Customization Guides

> How-to guides for extending CBX through its upgrade-safe customization layer — one directory per install, resolved by KenedoPlatform::p->getDirCustomization.…

Source: CBX documentation, version 4.0 preview (unreleased). Canonical page: https://docs.configbox.at/docs/4.0-preview/customization/. Last updated 2026-08-25.

---
**How-to guides for extending CBX** through its upgrade-safe customization layer — one
directory per install, resolved by `KenedoPlatform::p()->getDirCustomization()`. Its location is
**per platform**: `data/customization/` inside the component on Joomla,
`wp-content/plugins/configbox-customization/` on WordPress (a sibling of the plugin), and the
`Rovexo_ConfigboxCustomizations` module's `view/customizations/` directory on Magento 2 — see the
overview's §1.1 table. The guides write paths in the Joomla spelling (`data/customization/<x>`);
resolve `<x>` against your platform's directory. Where `functional/` describes *what* the app
does and `technical/` describes *how the current code is built*, this track is **task-oriented**: concrete
recipes for adding your own behavior without modifying (and later losing) core component files.

The customization layer is the supported extension point: files placed under `data/customization/` extend
or shadow their core counterparts and survive component updates. (Exactly *how* each kind resolves —
shadow, merge, register, or boot-time pre-emption, and which direction wins — varies per mechanism; the
**overview** maps all of it.) It is **gitignored** in this repository (it is the developer's/integrator's
local code), so these guides describe the structure and contracts you build against rather than checked-in
examples.

---

## Start here

- **[com_configbox_customization_overview.md](https://docs.configbox.at/docs/4.0-preview/customization/customization_overview)** — **Overview &
  extension-point map.** The orientation guide: what the customization layer is, the one resolution rule
  that governs almost all of it (a customization path and a core path, one preferred over the other —
  which way depends on the mechanism), a table of *every* extension point with where it resolves in code,
  and a decision guide ("I want to change X → use mechanism Y"). Read this before the individual guides.

**New extension points, and what changed under them:**
[Latest features → platform & extensibility](https://docs.configbox.at/docs/4.0-preview/features/latest/platform-and-extensibility) — the
what's-new cut for integrators: site-specific CLI commands, question types the AI can operate, custom
calc term types, payment connectors, on-screen help, and the move from a silent `false` to exceptions.
[Latest features](https://docs.configbox.at/docs/4.0-preview/features/latest/) is the whole track.

## Guides

- **[com_configbox_overriding_views_and_templates.md](https://docs.configbox.at/docs/4.0-preview/customization/overriding_views_and_templates)** —
  **Overriding views & templates.** The most common task: change a screen's markup via a template override
  (`templates/<view>/<layout>.php`), the three-slot template precedence chain, what variables a template
  has (`$this` is the view), the view-class vs. template precedence **asymmetry** (view classes are *not*
  "customization wins"), adding a brand-new view, and a worked example.
- **[com_configbox_custom_properties.md](https://docs.configbox.at/docs/4.0-preview/customization/custom_properties)** — **Creating custom Kenedo
  Properties.** End-to-end: how a `type` string resolves to your class + template, every lifecycle hook
  (request → validate → store → render → list → copy/delete) and when to override it, external storage,
  conditional applicability, attaching per-property CSS/JS, a complete worked `colorpicker` example, and a
  deployment checklist.
- **[com_configbox_help_customization.md](https://docs.configbox.at/docs/4.0-preview/customization/help_customization)** — **On-screen help.**
  Make the admin's help describe *your* install: append to (or `mode: replace`) any screen's note,
  add your own articles in a **Customizations** section of the guide, or shadow a shipped article by
  putting a file at the same path. One `help/` folder mirroring the guide's layout, images kept in the
  customization directory beside the file that uses them, nothing registered and no cache to clear.
  The counterpart to the fields you add — a customized form whose help still describes the stock
  screen is only half-delivered.
- **[com_configbox_extending_stock_models.md](https://docs.configbox.at/docs/4.0-preview/customization/extending_stock_models)** — **Extending
  stock models.** Add a field to (or tweak a field on) an existing model via
  `model_property_customization/` — the exact file/function/return contract, how the merge replaces vs.
  adds by `name`, the clone-then-change pattern for editing one core field, the migration that delivers the
  column, and a worked example.
- **[com_configbox_overriding_controllers_and_models.md](https://docs.configbox.at/docs/4.0-preview/customization/overriding_controllers_and_models)** —
  **Overriding controllers & models (behavior).** The precedence rule — **controllers, models, and view
  classes all load core-first (new-only)**, so the customization folders add *new* classes and don't shadow
  core ones — why changing an *existing* core class means `system_overrides/`, when to reach for that vs.
  observers vs. property injection, the `Cbcheckout→Configbox` legacy fallback, and worked examples.
- **[com_configbox_custom_rule_conditions.md](https://docs.configbox.at/docs/4.0-preview/customization/custom_rule_conditions)** — **Custom rule
  condition types.** Add a new "if…" to the Rule Editor: the `CustomCondition<Type>` naming/resolution
  contract, the three required methods (`getEvaluationResult` / `getConditionsPanelHtml` /
  `getConditionHtml`) and optional hooks, the `$selections` / `$conditionData` shapes and the
  `data-*`→`conditionData` bridge, performance notes (the evaluator is hot), and a worked `Weekday` example.
  (The engine is encoded; condition *types* are plaintext — no encoder needed.)
- **[com_configbox_custom_question_types.md](https://docs.configbox.at/docs/4.0-preview/customization/custom_question_types)** — **Custom question
  types.** Add a new kind of configurator input: why the **view folder** (`views/question_<type>/`) is what
  registers the type in the admin dropdown, the optional `ConfigboxQuestion<Type>` class and its *silent*
  fallback to the base class, the five-step template chain, per-type admin fields via
  `model_property_customization/questions.php` and `appliesWhen`, and the composite-value trap
  (`floatval()` of a JSON selection is `0`).
- **[com_configbox_question_types_and_ai.md](https://docs.configbox.at/docs/4.0-preview/customization/question_types_and_ai)** — **Question types
  the AI understands and controls.** The companion contract that makes a custom type *self-describing*, so
  the chat advisor and every headless client can operate it like a stock type: designing the selection
  shape, canonical storage (`getStorableValue`), the comparison contract (`isSameSelection` /
  `isEmptySelection`), the AI descriptors (`getSelectionFormatHint` / `getSelectionSchema` /
  `getChoiceList` / `getConstraintHints`), sub-value delegation for rules and pricing, the frontend
  registration helper, the **reveal contract** for collapse/expand page flows, and how to pin it all in
  API specs.
- **[com_configbox_custom_calc_term_types.md](https://docs.configbox.at/docs/4.0-preview/customization/custom_calc_term_types)** — **Custom calc
  term types.** Add a building block to formula calculations — usually how a composite question type
  reaches a price: eager loading from `calc_term_types/`, the class-name suffix as a *stored* identifier,
  the three abstract methods (`getTermResult` / `getTermsPanelHtml` / `getTermHtml`), why `getTermResult`
  is hot, and the deleted-question guard that keeps a stale term from taking the formula editor down.
- **[com_configbox_events_and_observers.md](https://docs.configbox.at/docs/4.0-preview/customization/events_and_observers)** — **Events &
  observers.** React to (or augment/compute for) CBX events — the safest, additive extension point:
  how the dispatcher works and registers observers (before/after built-ins), the three event styles
  (react / by-reference augment / `returnLast` compute), the **two-part deployment** (file +
  `#__configbox_connectors` row), the **event catalog with signatures**, the `onOrderPlaced`-aren't-events
  trap, and a worked order-webhook example.
- **[com_configbox_payment_connectors.md](https://docs.configbox.at/docs/4.0-preview/customization/payment_connectors)** — **Payment (PSP)
  connectors.** Add a payment method as a convention-based **folder** (no base class): the customization-first
  folder resolution, the file contract (`administration.php` metadata functions, `settings.php` admin form,
  `bridge.php` checkout hand-off, `result.php` confirmation, `ipn.php` callback handler), the **IPN class-name
  quirk** (`Ipn<ucwords(strtolower(name))>`), IPN security, and a worked offline-method example.
- **[com_configbox_assets_and_amd.md](https://docs.configbox.at/docs/4.0-preview/customization/assets_and_amd)** — **Assets (CSS) & JavaScript
  (AMD).** Add CSS/JS with no build step: the auto-detected entry points (`custom.css`, `custom.js`,
  `custom_questions.js`), the `configbox/custom` AMD namespace, the server→client `appConfig` gateway, the
  view-asset engine (per-view/per-property CSS + `moduleId::method` init calls, XHR-safe), registering
  third-party libs via `cbGetCustomRequirePaths`/`cbGetCustomRequireShims`, and the min/cache-busting rules
  (don't `.min` your custom JS).
- **[com_configbox_admin_ui_migration.md](https://docs.configbox.at/docs/4.0-preview/customization/admin_ui_migration)** — **Admin UI migration
  (major release).** What changed in the backend form/list markup, CSS class names (the new `cb-*` prefix,
  Bootstrap 5 components, `.cb-content` scoping) and JS — and how to amend custom admin CSS/JS or template
  overrides. The stable `.trigger-*` (JS hooks) and `.property-*` (property styling) conventions that do
  **not** change. Maintained as each migration slice ships.
- **[com_configbox_custom_cli_commands.md](https://docs.configbox.at/docs/4.0-preview/customization/custom_cli_commands)** — **Custom CLI
  commands.** Add site-specific commands to the ConfigBox CLI suite under the reserved `custom`
  namespace (WordPress: `wp configbox custom <command>`): the one-file contract
  (`cli/commands.php` returns name → `shortdesc`/`synopsis`/`callback`), the callback's
  args/options/exit-code interface, and the failure-isolation design — the file loads only when the
  `custom` dispatcher runs, so a broken commands file can never take down the stock commands.
- **[com_configbox_language_overrides.md](https://docs.configbox.at/docs/4.0-preview/customization/language_overrides)** — **Language overrides.**
  Change displayed UI text via `language_overrides/<tag>/overrides.ini` (loaded last, wins): the
  **two-text-systems distinction** (INI/UI strings here vs. admin-authored content in `#__configbox_strings`),
  the load order, how to find a string's key, INI syntax gotchas, and per-language deployment.
- **[com_configbox_system_overrides_and_boot_hooks.md](https://docs.configbox.at/docs/4.0-preview/customization/system_overrides_and_boot_hooks)** —
  **System overrides & boot hooks (escape hatch).** Replace a framework/helper class that has no per-type
  loader, and run PHP at boot/DB-connect: how eager pre-emption beats the lazy autoloader (and its hard
  limit — the class mustn't already be loaded), the `_`-first load order, the boot-hook functions
  (`cbGetCustomRequirePaths`, `getPostDbConnectQueries`, …), the `getInitQueries.php` DB-connect hook, the
  `data/store/private/settings/` per-install slot, and the standing re-diff-after-update maintenance cost.

The customization track now covers every supported extension point. Future additions would be incremental
(new mechanisms introduced by the component) or deeper worked examples.

## Version migration

- **Customization code migration to CBX 4** — now lives **inside the component** at
  [`../migration-to-cb4/`](https://docs.configbox.at/docs/4.0-preview/migration-to-cb4/)
  so it ships with releases and reaches the WordPress/Magento 2 projects (all mount the same component
  repo). The running record of **breaking changes** in the CBX 4 refactor and how to realign your
  customization code — a dated breaking-changes log plus a playbook per affected customization kind (what
  the core auto-converts for you, and what you must edit by hand). Start here when a customization stops
  working after an update; it is **maintained as each CBX 4 slice ships**.

---

## Prerequisites

Read `technical/com_configbox_kenedo_mvc.md` (§4, Kenedo Properties) first if the property-driven model is
unfamiliar, and `technical/com_configbox_migrations.md` for delivering any DB schema a customization needs
(the **customization migration track**, `data/customization/updates/`).

## Where customization code lives (quick map)

Shown at its Joomla location; on WordPress the same tree sits in
`wp-content/plugins/configbox-customization/`, on Magento 2 in
`app/code/Rovexo/ConfigboxCustomizations/view/customizations/` (overview §1.1).

```
data/customization/
  controllers/                       ← add NEW controllers (core-first: does NOT shadow a core controller)
  models/                            ← add NEW models (core-first: does NOT shadow a core model)
  views/                             ← add NEW view classes (core-first: does NOT shadow a core view)
  templates/                         ← override view templates / markup (customization-first)
  properties/        + tmpl/         ← custom Kenedo property types (+ form templates)
  model_property_customization/      ← inject/retune property defs on stock models (merge)
  question_types/                    ← custom question type classes (ConfigboxQuestion<Type>)
  rule_condition_types/              ← custom rule condition types (CustomCondition<Type>)
  calc_term_types/                   ← custom calc term types (CustomCalcTerm<Type>)
  custom_observers/                  ← event observers (+ a #__configbox_connectors row)
  psp_connectors/                    ← payment method connectors (folder per method)
  system_overrides/                  ← replace a core class / boot hooks (escape hatch)
  language_overrides/<tag>/          ← overrides.ini — change UI text (loaded last)
  assets/  (css, javascript)         ← custom CSS / AMD JS modules (configbox/custom)
  cli/commands.php                   ← custom CLI commands (`wp configbox custom <command>`)
  updates/                           ← customization-track DB migrations
```

For the precise resolution rule per mechanism (and the per-kind precedence asymmetries), see the
**[overview](https://docs.configbox.at/docs/4.0-preview/customization/customization_overview)**.